Skip to content

Latest commit

 

History

History
118 lines (97 loc) · 3.04 KB

AdvancedUsage.md

File metadata and controls

118 lines (97 loc) · 3.04 KB

Advanced usage

Tags

YACL has basic support of CBOR tags.

To encode a tag, use the following constructor:

CBOR(int tag_value, CBOR tag_item);

To decode tags, use the following methods:

int tag_val = cbor_obj.get_tag_value();
CBOR tag_item = cbor_obj.get_tag_item();

For instance, to tag http://www.example.com as an URI (tag 32, see https://tools.ietf.org/html/rfc7049#section-2.4):

CBOR uri = CBOR("http://www.example.com");
CBOR tagged_uri = CBOR(32, uri);

Likewise, to decode a received CBOR tag containing an URI:

char decoded_uri[50]; //Reserve 50 characters for the string
tagged_uri.get_tag_item().get_string(decoded_uri);
Serial.println(decoded_uri);

Type decoding

Casting of CBOR objects to native types (int, float, string, etc.) is not safe. For instance, casting a CBOR 8-bits integer to a string will raise no error, but the behavior is undefined (and may lead to memory corruption). Hence, before attempting such casting, the type of the CBOR should be determined using is_*() methods. Please find bellow the list of is_*() available methods:

//Unsigned integers
bool is_uchar();
bool is_ushort();
bool is_uint();
bool is_ulong();
bool is_ulong_long();

bool is_uint8();
bool is_uint16();
bool is_uint32();
bool is_uint64();

//Signed integers
bool is_schar();
bool is_short();
bool is_int();
bool is_long();
bool is_long_long();

bool is_int8();
bool is_int16();
bool is_int32();
bool is_int64();

//Caution: char can be either signed or unsigned.
//is_char() assumes that the char type can represent a negative number,
//which may or may not be the case on your machine.
bool is_char();

//Floating point values
bool is_float16();
bool is_float32();
bool is_float64();

//Other types
bool is_null();
bool is_bool();
bool is_string();
bool is_array();
bool is_pair();
bool is_tag();

Note that for (unsigned) integers and floats, is_type*() indicates that the CBOR-encoded number can be represented using a type of size * bits. Similarly for standard types, is_*() indicates that the CBOR-encoded number can be represented with type *. For instance:

CBOR val = CBOR(123);

Serial.println(val.is_uint8);  //True
Serial.println(val.is_uint16); //True
Serial.println(val.is_uint32); //True
Serial.println(val.is_uint64); //True
CBOR val = CBOR(1230);

Serial.println(val.is_uint8);  //False
Serial.println(val.is_uint16); //True
Serial.println(val.is_uint32); //True
Serial.println(val.is_uint64); //True

Is data copied when accessing elements of an Array, a Pair or a tag item ?

No. This means that when doing this, for example:

CBOR arr = CBORArray();
arr.append(0);
arr.append(1);

CBOR ele1 = arr[1];

Then, the actual data is stored in arr, and only in arr. Hence, modifications of arr can impact ele1, and vice versa.

If one wishes to do a copy, then he/she can use the copy constructor:

CBOR arr = CBORArray();
arr.append(0);
arr.append(1);

CBOR ele1 = CBOR(arr[1]);

In this case, ele1 actually stores a copy of the CBOR representation of 1.