Add NEGINT serialization test & document negint set behavior

doc/source/api/type_0_1.rst

@@ -45,6 +45,19 @@ Actual Type of the integer can be checked using :ref:`item types API <item-types
 
 An integer item is created with one of the four widths. Because integers' `storage is bundled together with the handle </internal#c.cbor_item_t.data>`_, the width cannot be changed over its lifetime.
 
+Warning
+---------
+Due to the fact that CBOR negative integers represent integers in the range :math:`[-1, -2^N]`, ``cbor_set_uint`` API is somewhat counter-intuitive as the resulting logical value is 1 less. This behavior is necessary in order to permit uniform manipulation with the full range of permitted values. For example, the following snippet
+
+.. code-block:: c
+
+    cbor_item_t * item = cbor_new_int8();
+    cbor_mark_negint(item);
+    cbor_set_uint8(0);
+
+will produce an item with the logical value of :math:`-1`. There is, however, an upside to this as well: There is only one representation of zero.
+
+
 Retrieving values
 ------------------------
 .. function:: uint8_t cbor_get_uint8(const cbor_item_t * item)

test/cbor_serialize_test.c

@@ -38,12 +38,50 @@ static void test_serialize_uint64(void **state) {
 	assert_memory_equal(buffer, ((unsigned char[]){ 0x1B, 0x00, 0x00, 0x00, 0xE8, 0xD4, 0xA5, 0x10, 0x00 }), 9);
 }
 
+
+static void test_serialize_negint8(void **state) {
+	cbor_item_t * item = cbor_new_int8();
+	cbor_set_uint8(item, 0);
+	cbor_mark_negint(item);
+	assert_int_equal(1, cbor_serialize(item, buffer, 512));
+	assert_memory_equal(buffer, (unsigned char[]){ 0x20 }, 1);
+}
+
+static void test_serialize_negint16(void **state) {
+	cbor_item_t * item = cbor_new_int16();
+	cbor_set_uint16(item, 1000);
+	cbor_mark_negint(item);
+	assert_int_equal(3, cbor_serialize(item, buffer, 512));
+	assert_memory_equal(buffer, ((unsigned char[]){ 0x39, 0x03, 0xE8 }), 3);
+}
+
+static void test_serialize_negint32(void **state) {
+	cbor_item_t * item = cbor_new_int32();
+	cbor_set_uint32(item, 1000000);
+	cbor_mark_negint(item);
+	assert_int_equal(5, cbor_serialize(item, buffer, 512));
+	assert_memory_equal(buffer, ((unsigned char[]){ 0x3A, 0x00, 0x0F, 0x42, 0x40 }), 5);
+}
+
+static void test_serialize_negint64(void **state) {
+	cbor_item_t * item = cbor_new_int64();
+	cbor_set_uint64(item, 1000000000000);
+	cbor_mark_negint(item);
+	assert_int_equal(9, cbor_serialize(item, buffer, 512));
+	assert_memory_equal(buffer, ((unsigned char[]){ 0x3B, 0x00, 0x00, 0x00, 0xE8, 0xD4, 0xA5, 0x10, 0x00 }), 9);
+}
+
+
 int main(void) {
 	const UnitTest tests[] = {
 		unit_test(test_serialize_uint8),
 		unit_test(test_serialize_uint16),
 		unit_test(test_serialize_uint32),
-		unit_test(test_serialize_uint64)
+		unit_test(test_serialize_uint64),
+		unit_test(test_serialize_negint8),
+		unit_test(test_serialize_negint16),
+		unit_test(test_serialize_negint32),
+		unit_test(test_serialize_negint64)
 	};
 	return run_tests(tests);
 }