CBOR.js - JavaScript API
Abstract
This document describes a JavaScript API for encoding and decoding data in the
CBOR format. Through platform independent definitions of deterministic encoding and
a textual representation of CBOR data, compatible implementations could,
together with the rich set of data types offered by CBOR, provide
a viable alternative for applications that currently use JSON.
Table of Contents
1. Introduction
This document describes a JavaScript API for encoding and decoding data in the
CBOR [RFC8949] format.
The API loosely mimics the "JSON" object by exposing a single global object,
unsurprisingly named "CBOR".
To minimize the need for application developers having detailed knowledge of CBOR,
the CBOR.js API provides a set of high level wrapper objects.
The wrapper objects are used for encoding CBOR data items,
as well as being the result of CBOR decoding.
The CBOR.js API provides some specific features including:
Note: in this specification CBOR data items are subsequently referred to as CBOR objects.
2. CBOR Wrapper Objects
This section describes the wrapper objects and their specific methods.
Note that using the "new" operator with the wrapper objects
is flagged as an error.
The following table lists the wrapper objects and their relation to
the CBOR objects supported by this specification:
- See also Integer Numbers.
- See also Floating Point Numbers.
Note that this implementation does not support CBOR "simple" values beyond
true, false, null, and the three floating point variants.
See also Common Wrapper Methods.
2.1. CBOR.Int
Syntax | CBOR.Int(value) |
Description | Constructor. Creates a CBOR integer wrapper object.
See also Integer Numbers. |
|
Parameter | Type | Description |
value | Number | Integer to be wrapped. |
|
Returns | Description |
CBOR.Int | Wrapper object. |
2.1.1. CBOR.Int Methods
2.1.1.1. getInt()
Syntax | getInt() |
Description | Reads CBOR integer in the range of -253-1 to 253-1.
See also getBigInt(). |
|
Returns | Description |
Number | Decoded integer. |
2.1.1.2. getBigInt()
Syntax | getBigInt() |
Description | Reads CBOR integer of any size.
See also Integer Numbers. |
|
Returns | Description |
BigInt | Decoded big integer. |
2.2. CBOR.BigInt
Syntax | CBOR.BigInt(value) |
Description | Constructor. Creates a CBOR big integer wrapper object.
See also Integer Numbers. |
|
Parameter | Type | Description |
value | BigInt | Big integer to be wrapped. |
|
Returns | Description |
CBOR.BigInt | Wrapper object. |
2.2.1. CBOR.BigInt Methods
2.2.1.1. getBigInt()
Syntax | getBigInt() |
Description | Reads CBOR integer of any size.
See also Integer Numbers. |
|
Returns | Description |
BigInt | Decoded big integer. |
2.3. CBOR.Float
Syntax | CBOR.Float(value) |
Description | Constructor. Creates a CBOR floating point wrapper object.
See also Floating Point Numbers. |
|
Parameter | Type | Description |
value | Number | Floating point number to be wrapped. |
|
Returns | Description |
CBOR.Float | Wrapper object. |
2.3.1. CBOR.Float Methods
2.3.1.1. getFloat()
Syntax | getFloat() |
Description | Reads CBOR floating point object. |
|
Returns | Description |
Number | Decoded floating point number. |
2.3.2. CBOR.Float Properties
2.3.2.1. length
Name | Type | Description |
length | Number | Length in bytes of the underlying CBOR IEEE 754 type. |
2.4. CBOR.String
Syntax | CBOR.String(textString) |
Description | Constructor. Creates a CBOR text string wrapper object. |
|
Parameter | Type | Description |
textString | String | String to be wrapped. |
|
Returns | Description |
CBOR.String | Wrapper object. |
2.4.1. CBOR.String Methods
2.4.1.1. getString()
Syntax | getString() |
Description | Reads CBOR text string. |
|
Returns | Description |
String | Decoded text string. |
2.5. CBOR.Bytes
Syntax | CBOR.Bytes(byteString) |
Description | Constructor. Creates a CBOR byte string wrapper object. |
|
Parameter | Type | Description |
byteString | Uint8Array | Binary data to be wrapped. |
|
Returns | Description |
CBOR.Bytes | Wrapper object. |
2.5.1. CBOR.Bytes Methods
2.5.1.1. getBytes()
Syntax | getBytes() |
Description | Reads CBOR byte string. |
|
Returns | Description |
Uint8Array | Decoded byte string. |
2.6. CBOR.Boolean
Syntax | CBOR.Boolean(value) |
Description | Constructor. Creates a CBOR boolean wrapper object. |
|
Parameter | Type | Description |
value | Boolean | Boolean to be wrapped. |
|
Returns | Description |
CBOR.Boolean | Wrapper object. |
2.6.1. CBOR.Boolean Methods
2.6.1.1. getBoolean()
Syntax | getBoolean() |
Description | Reads CBOR boolean. |
|
Returns | Description |
Boolean | Decoded boolean. |
2.7. CBOR.Null
Syntax | CBOR.Null() |
Description | Constructor. Creates a CBOR null wrapper object.
See also isNull(). |
|
Returns | Description |
CBOR.Null | Wrapper object. |
2.8. CBOR.Array
Syntax | CBOR.Array() |
Description | Constructor. Creates a CBOR array wrapper object. |
|
Returns | Description |
CBOR.Array | Wrapper object. |
2.8.1. CBOR.Array Methods
2.8.1.1. add()
Syntax | add(object) |
Description | Adds CBOR wrapper object to the array. |
|
Parameter | Type | Description |
object | CBOR.Wrapper | Object to be appended to the current array. |
|
Returns | Description |
this | Current object. |
2.8.1.2. get()
Syntax | get(index) |
Description | Fetches CBOR wrapper object.
If index is out of range, an exception is thrown. |
|
Parameter | Type | Description |
index | Number | Index (0..length-1) of object. |
|
Returns | Description |
CBOR.Wrapper | Retrieved object. |
2.8.1.3. toArray()
Syntax | toArray() |
Description | Copies array. |
|
Returns | Description |
[...] | JavaScript array holding a copy of current CBOR.Wrapper objects. |
2.8.1.4. getArray()
Syntax | getArray() |
Description | Get array object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing array elements. |
|
Returns | Description |
CBOR.Array | Current object. |
2.8.2. CBOR.Array Properties
2.8.2.1. length
Name | Type | Description |
length | Number | Number of objects in the array. |
2.9. CBOR.Map
Syntax | CBOR.Map() |
Description | Constructor. Creates a CBOR map wrapper object. |
|
Returns | Description |
CBOR.Map | Wrapper object. |
2.9.1. CBOR.Map Methods
2.9.1.1. set()
Syntax | set(key, value) |
Description | Sets map entry.
If key entry is already defined, an exception is thrown.
|
|
Parameter | Type | Description |
key | CBOR.Wrapper | Key (name) wrapper object. |
value | CBOR.Wrapper | Value wrapper object. |
|
Returns | Description |
this | Current object. |
2.9.1.2. get()
Syntax | get(key) |
Description | Gets map entry.
If key entry is undefined, an exception is thrown. |
|
Parameter | Type | Description |
key | CBOR.Wrapper | Key (name) wrapper object. |
|
Returns | Description |
CBOR.Wrapper | Retrieved object. |
2.9.1.3. getConditional()
Syntax | getConditional(key, defaultValue) |
Description | Gets map entry conditionally. |
|
Parameter | Type | Description |
key | CBOR.Wrapper | Key (name) wrapper object. |
defaultValue | CBOR.Wrapper | Value to return if key entry is undefined.
defaultValue may be null . |
|
Returns | Description |
CBOR.Wrapper | Retrieved or default object. |
2.9.1.4. containsKey()
Syntax | containsKey(key) |
Description | Checks map for key presence. |
|
Parameter | Type | Description |
key | CBOR.Wrapper | Key (name) wrapper object. |
|
Returns | Description |
Boolean | true or false . |
2.9.1.5. remove()
Syntax | remove(key) |
Description | Removes map entry.
If key entry is undefined, an exception is thrown. |
|
Parameter | Type | Description |
key | CBOR.Wrapper | Key (name) wrapper object. |
|
Returns | Description |
CBOR.Wrapper | Removed object (value component). |
2.9.1.6. getKeys()
Syntax | getKeys() |
Description | Get map keys. |
|
Returns | Description |
[...] | JavaScript array holding a copy of current CBOR.Wrapper map keys. |
2.9.1.7. getMap()
Syntax | getMap() |
Description | Get map object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing map keys. |
|
Returns | Description |
CBOR.Map | Current object. |
2.9.1.8. setSortingMode()
Syntax | setSortingMode(preSortedKeys) |
Description | Sets the current sorting mode of the
CBOR.Map() object during
set() operations.
Typical usage:
let map = CBOR.Map().setSortingMode(true)
This method may be called multiple times which could be
useful if you have a moderate set of unsorted meta data keys
combined with a sorted large table-like set of keys.
Note that this method has no effect on decoding operations. |
|
Parameter | Type | Description |
preSortedKeys | Boolean | If true ,
keys must be provided in (CBOR wise) ascending order
which can improve performance for maps having a huge number of keys.
Improper key order will cause an exception to be thrown.
By default map keys are sorted internally. |
|
Returns | Description |
this | Current object. |
2.9.2. CBOR.Map Properties
2.9.2.1. length
Name | Type | Description |
length | Number | Number of map entries. |
2.10. CBOR.Tag
Syntax | CBOR.Tag(tagNumber, object) |
Description | Constructor. Creates a CBOR tag wrapper object. |
|
Parameter | Type | Description |
tagNumber | BigInt | Tag number. |
object | CBOR.Wrapper | Object to be wrapped in a tag. |
|
Returns | Description |
CBOR.Tag | Wrapper object. |
2.10.1. CBOR.Tag Methods
2.10.1.1. getTagNumber()
Syntax | getTagNumber() |
Description | Reads CBOR tag number. |
|
Returns | Description |
BigInt | Decoded tag number. |
2.10.1.2. getTaggedObject()
Syntax | getTaggedObject() |
Description | Reads tagged CBOR object. |
|
Returns | Description |
CBOR.Wrapper | Retrieved object. |
2.10.1.3. getTag()
Syntax | getTag() |
Description | Get tag object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing the tag object. |
|
Returns | Description |
CBOR.Tag | Current object. |
3. Common Wrapper Methods
The CBOR wrapper objects
support a set of common methods, described in this sub section.
3.1. encode()
Syntax | encode() |
Description | Encodes this object.
|
|
Returns | Description |
Uint8Array | CBOR encoded data. |
3.2. clone()
Syntax | clone() |
Description | Creates a new instance of this object, initialized
with the original CBOR content. |
|
Returns | Description |
CBOR.Wrapper | Copy of object. |
3.3. equals()
Syntax | equals(object) |
Description | Compares this object with another object with respect to CBOR data. |
|
Parameter | Type | Description |
object | CBOR.Wrapper | The object to compare with. |
|
Returns | Description |
Boolean | true if this object is equal to object ,
otherwise false . |
3.4. toDiag()
Syntax | toDiag(prettyPrint) |
Description | Renders this object in Diagnostic Notation.
In similarity to encode(), this method always produce
data in Deterministic Encoding, irrespective to how
the data was created.
See also: toString(). |
|
Parameter | Type | Description |
prettyPrint | Boolean | If prettyPrint is true ,
additional white space is inserted between elements to make the result
easier to read. |
|
Returns | Description |
String | Textual version of the wrapped CBOR content. |
3.5. toString()
Syntax | toString() |
Description | Renders this object in Diagnostic Notation.
Equivalent to calling toDiag()
with a true argument. |
|
Returns | Description |
String | Textual version of the wrapped CBOR content. |
3.6. isNull()
Syntax | isNull() |
Description | Checks for CBOR null .
Note: if checkForUnread()
is used, the current object will only be regarded as "read"
if it actually is a CBOR null item.
See also CBOR.Null(). |
|
Returns | Description |
Boolean | Returns true if the current object
holds a CBOR null item, otherwise false
is returned. |
3.7. checkForUnread()
Syntax | checkForUnread() |
Description | Checks if the current object including possible child objects has been read
(like calling getInt()).
If any of the associated objects have not been read, an exception will be thrown.
The purpose of this method is to detect possible misunderstandings between parties
using CBOR based protocols. Together with the strict type checking performed
by the CBOR.js API, a programmatic counterpart to schema based processing
can be achieved.
Note that array get(),
map get(), and
tag getTaggedObject()
only locate objects,
and thus do not count as "read".
Also see
getArray(),
getMap(),
getTag(), and
scan(). |
|
Returns | Description |
this | Current object. |
3.8. scan()
Syntax | scan() |
Description | Scans current object as well as possible child objects
in order to make them appear as "read".
This is only meaningful in conjunction with
checkForUnread(). |
|
Returns | Description |
this | Current object. |
4. Decoding CBOR
CBOR decoding comes in two flavors, binary and
Diagnostic Notation.
Both decoders store the result in the same set of CBOR.Wrapper
objects,
used for encoding CBOR data.
This section lists the decoder methods.
4.1. CBOR.decode()
Syntax | CBOR.decode(cbor) |
Description | Decodes a CBOR object.
This method assumes that the CBOR data adheres to
Deterministic Encoding,
otherwise exceptions will be thrown.
Any additional data after the CBOR object will also cause
exceptions to be thrown. |
|
Parameter | Type | Description |
cbor | Uint8Array | The data (bytes) to be decoded. |
|
Returns | Description |
CBOR.Wrapper | CBOR wrapper object. |
4.2. CBOR.initExtended()
Syntax | CBOR.initExtended(cbor, sequenceFlag, nonDeterministic) |
Description | Initiates an extended CBOR decoder.
This decoding method presumes that the actual
decoding is performed by one or more (for sequences only) calls to
CBOR.decodeExtended(). |
|
Parameter | Type | Description |
cbor | Uint8Array | The data (bytes) to be decoded. |
sequenceFlag | Boolean | If true , CBOR.decodeExtended()
will return immediately after decoding a CBOR object, otherwise
any additional data after the CBOR object will cause exceptions to be thrown. |
nonDeterministic | Boolean | If true the decoder will accept CBOR code
which violates the Deterministic Encoding rules.
This option may be needed for dealing with "legacy"
CBOR implementations.
The flag disables the strict map sorting requirement and the preferred
serialization of numbers (=shortest). |
|
Returns | Description |
Decoder | Internal decoder object for usage with
CBOR.decodeExtended(). |
4.3. CBOR.decodeExtended()
Syntax | CBOR.decodeExtended(decoder) |
Description | Decodes a CBOR object.
If the sequenceFlag in the call to
CBOR.initExtended()
is true , each call to
CBOR.decodeExtended()
causes the internal decoder to move to the next (possible but unprocessed) CBOR object.
When there is no more data to decode, null is returned. |
|
Parameter | Type | Description |
decoder | Decoder | Internal decoder object. |
|
Returns | Description |
CBOR.Wrapper | CBOR wrapper object or null . |
4.4. CBOR.diagDecode()
Syntax | CBOR.diagDecode(cborText) |
Description | Decodes a CBOR object provided in Diagnostic Notation.
See also CBOR.diagDecodeSequence(). |
|
Parameter | Type | Description |
cborText | String | CBOR in textual format. |
|
Returns | Description |
CBOR.Wrapper | CBOR wrapper object. |
4.5. CBOR.diagDecodeSequence()
Syntax | CBOR.diagDecodeSequence(cborText) |
Description | Decodes a CBOR object provided in Diagnostic Notation.
Unlike CBOR.diagDecode(),
this method also accepts CBOR sequences, using a comma
character (',' ) as a separator. |
|
Parameter | Type | Description |
cborText | String | CBOR in textual format. |
|
Returns | Description |
[...] | Array holding one or more CBOR wrapper objects. |
5. Utility Methods
The following utility methods are unrelated to CBOR but have been included
here because they are a part of the current CBOR.js implementation.
5.1. CBOR.addArrays()
Syntax | CBOR.addArrays(a, b) |
Description | Adds two arrays. |
|
Parameter | Type | Description |
a | Uint8Array | First array. |
b | Uint8Array | Second array. |
|
Returns | Description |
Uint8Array | Concatenation of array a and b . |
5.2. CBOR.compareArrays()
Syntax | CBOR.compareArrays(a, b) |
Description | Compares two arrays lexicographically. |
|
Parameter | Type | Description |
a | Uint8Array | First array. |
b | Uint8Array | Second array. |
|
Returns | Description |
Number | If a and b are identical,
0 is retuned.
If a > b ,
a positive number is returned.
If a < b ,
a negative number is returned. |
5.3. CBOR.toHex()
Syntax | CBOR.toHex(byteArray) |
Description | Encodes binary data to hexadecimal. |
|
Parameter | Type | Description |
byteArray | Uint8Array | Zero or more bytes to be encoded. |
|
Returns | Description |
String | Hexadecimal encoded data. |
5.4. CBOR.fromHex()
Syntax | CBOR.fromHex(hexString) |
Description | Decodes hexadecimal data into binary. |
|
Parameter | Type | Description |
hexString | String | String with zero or more hexadecimal pairs. Each pair represents one byte. |
|
Returns | Description |
Uint8Array | The resulting binary (bytes). |
5.5. CBOR.toBase64Url()
Syntax | CBOR.toBase64Url(byteArray) |
Description | Encodes binary data to base64Url. |
|
Parameter | Type | Description |
byteArray | Uint8Array | Zero or more bytes to be encoded. |
|
Returns | Description |
String | Base64Url encoded data. |
5.6. CBOR.fromBase64Url()
Syntax | CBOR.fromBase64Url(base64) |
Description | Decodes base64Url encoded data into binary.
Note that this method is permissive; it accepts
base64 encoded data as well as data with or without
'=' padding. |
|
Parameter | Type | Description |
base64 | String | String in base64Url notation. The string may be empty. |
|
Returns | Description |
Uint8Array | The resulting binary (bytes). |
6. JavaScript Number Considerations
Since JavaScript natively only supports Number
(backed
by 64-bit IEEE 754 floating point data), and BigInt
(offering unlimited integers), it is important to understand how these
number types are mapped to CBOR which offers
two variants of integers and three variants of floating point types.
6.1. Integer Numbers
Due to the Number.MAX_SAFE_INTEGER limitation, CBOR
protocols using integer elements where the magnitude may exceed
253-1, must
for such elements turn to BigInt
,
otherwise run-time errors may occur when accessing integer data using
getInt() or
during creation of integers using
CBOR.Int().
That is, for creation of such integers,
CBOR.BigInt()
is the proper solution, while access requires
getBigInt(),
which for convenience reasons is supported by both of the integer wrapper types.
Note that selecting CBOR.BigInt()
or CBOR.Int() only affects the maximum
numeric range with respect to JavaScript limits, not the CBOR encoding.
During CBOR decoding, the selection between
CBOR.BigInt()
and CBOR.Int() is governed by the decoded value
with respect to JavaScript limits.
The selection between the CBOR unsigned and negative
integer variants is dealt with by the CBOR.js implementation;
transparent to the API.
6.2. Floating Point Numbers
Although CBOR encoding depends on 16, 32, and 64-bit IEEE 754
variants, the CBOR.js implementation makes this
transparent; the API only exposes the Number
type.
See also CBOR.Float().
7. Diagnostic Notation
Creating CBOR data in diagnostic notation (as described in section 8 of RFC 8949),
is provided by the toString() method.
However, through the CBOR.diagDecode()
method, CBOR data may also be provided in diagnostic (textual) notation,
making CBOR useful for local "config" and test data files as well.
Due to the
Deterministic Encoding
scheme used by CBOR.js, CBOR data can be bidirectionally
converted between its native (binary) format and diagnostic notation
without getting corrupted. Note though that text-binary-text "roundtrips"
do not necessarily return identical text: 0x10
used
as diagnostic notation input will return 16
as
diagnostic notation output.
The following table shows how CBOR objects should be represented in
diagnostic notation:
CBOR Object | Syntax | Notes | Description |
|
/ comment text / |
7 |
Multi-line comment.
Multi-line comments are treated as whitespace and may thus also be used
between CBOR objects.
|
# comment text |
7 |
Single-line comment.
Single-line comments are terminated by a newline character ('\n' ) or EOF .
Single-line comments may also terminate lines holding regular CBOR items.
|
integer |
{sign}{0b |0o |0x }n |
1, 2 |
Arbitrary sized integers without fractional components or exponents.
See also CBOR integer encoding.
For input data in diagnostic notation, binary, octal, and hexadecimal notation
is also supported by prepending numbers with 0b , 0o , and 0x respectively.
The latter also permit arbitrary insertions of '_' characters between digits to
enable grouping of data like 0b100_000000001 .
|
bignum |
floating point |
{sign}n. n{e± n} |
1, 2 |
Floating point values
must include a decimal point and an optional exponent.
See also CBOR floating point encoding.
|
NaN |
|
Not a number.
See also CBOR floating point encoding.
|
{sign}Infinity |
2 |
Infinity.
See also CBOR floating point encoding.
|
byte string |
h' hex data' |
3, 6 |
Byte data provided in hexadecimal notation.
Each byte must be represented by two hexadecimal digits.
|
b64' base64 data' |
3, 6, 7 |
Byte data provided in base64 or base64URL notation.
Padding with '=' characters is optional.
|
' text' |
4, 5, 7 |
Byte data provided as UTF-8 encoded text. |
<< object >> |
7 |
Construct holding a CBOR object which is subsequently embedded in a byte string. |
text string |
" text"
| 4, 5 |
UTF-8 encoded text string. |
true |
true |
|
Boolean value. |
false | false |
null |
null |
|
Null value. |
array |
[ objects ] |
|
Array with zero or more comma separated CBOR objects. |
map |
{ key: value } |
|
Map with zero or more comma separated key/value pairs.
Keys and values are expressed as CBOR objects.
|
tag |
n( object ) |
1 |
Tag holding a CBOR object. |
|
, |
7 |
Separator character for CBOR sequences. |
- The letter n in the Syntax column denotes one or more digits.
- The optional {sign} must be a single hyphen (
'-'
) character.
-
Whitespace characters
(
' '
, '\t'
, '\r'
, '\n'
)
inside of string quotes are ignored.
-
Whitespace characters
(
'\t'
, '\r'
, '\n'
)
inside of string quotes become a part of the text.
To avoid getting newline characters ('\n'
)
included in multi-line text strings,
a line continuation marker consisting of a backslash ('\'
)
immediately preceding the newline may be used.
-
Text strings may also include JavaScript compatible escape sequences
(
'\''
, '\"'
, '\\'
,
'\b'
, '\f'
, '\n'
,
'\r'
, '\t'
, '\u
hhhh'
).
- Zero-length strings (
''
) return byte strings of length zero.
-
Only applicable for input.
That is, toString() does not produce this item.
8. Deterministic Encoding
This section is primarily targeting implementers of CBOR tools.
While there are different ways you can encode certain CBOR objects,
this is non-trivial to support in a generic platform API without
adding complexity and that for little provable gain.
Therefore the CBOR.js API defines specific (non-variant)
encodings, aka "Deterministic Encoding". The chosen encoding
model is compatible with most existing CBOR decoders.
However, to not limit CBOR.js to new applications only,
deterministic encoding checking may optionally be turned off
for accepting input from "legacy" CBOR encoders.
The encoding scheme adheres to section 4.2 of RFC 8949, but adds
a few constraints (denoted by RFC+), where the RFC offers choices.
The encoding rules are as follows:
-
RFC+: Floating point and integer objects must be treated as distinct types
regardless of their numeric value. This is compliant with
Rule 2 in section 4.2.2 of RFC 8949.
-
RFC: Integers, represented by the integer and
bignum types, must use the integer
type if the value is between -264
and 264-1,
otherwise the bignum type must be used.
The following table holds a few sample values and their proper CBOR encoding:
Value | Encoding |
0 | 00 |
-1 | 20 |
255 | 18ff |
256 | 190100 |
-256 | 38ff |
-257 | 390100 |
1099511627775 | 1b000000ffffffffff |
18446744073709551615 | 1bffffffffffffffff |
18446744073709551616 | c249010000000000000000 |
-18446744073709551616 | 3bffffffffffffffff |
-18446744073709551617 | c349010000000000000000 |
Note that integers must not be supplied with
leading zero bytes (like 1900ff) unless the
CBOR representation offers no alternative (like 1b000000ffffffffff).
Note that the integer encoding scheme above does not always return the
most compact representation; the value
1099511627775
(0xffffffffff)
would actually yield two bytes less using the bignum type.
-
RFC+: Floating point data must use the shortest IEEE 754
variant and associated CBOR encoding.
The following table holds floating point values needing special considerations
as well as a small set of "edge cases":
Value | Encoding |
0.0 | f90000 |
-0.0 | f98000 |
Infinity | f97c00 |
-Infinity | f9fc00 |
NaN | f97e00 |
Assorted Edge Cases |
-5.960464477539062e-8 | fbbe6fffffffffffff |
-5.960464477539063e-8 | f98001 |
-5.960464477539064e-8 | fbbe70000000000001 |
-5.960465188081798e-8 | fab3800001 |
0.00006097555160522461 | f903ff |
65504.0 | f97bff |
65504.00390625 | fa477fe001 |
65536.0 | fa47800000 |
10.559998512268066 | fa4128f5c1 |
10.559998512268068 | fb40251eb820000001 |
3.4028234663852886e+38 | fa7f7fffff |
3.402823466385289e+38 | fb47efffffe0000001 |
1.401298464324817e-45 | fa00000001 |
1.4012986313726115e-45 | fb36a0000020000000 |
1.1754942106924411e-38 | fa007fffff |
5.0e-324 | fb0000000000000001 |
-1.7976931348623157e+308 | fbffefffffffffffff |
Note that NaN "signaling" (like f97e01),
must be flagged as an error.
Note that the shortest encoding may result in subnormal
numbers like f98001.
-
RFC: Map keys must be sorted in the bytewise lexicographic
order of their deterministic encoding.
Duplicate keys must be rejected.
-
RFC+: Since CBOR encoding according to this specification
maintains type and data uniqueness, there are no specific restrictions or
tests needed in order to determine map key equivalence.
As an example, the floating point numbers 0.0 and
-0.0, and the integer number 0
represent the distinct keys
f90000, f98000, and 00 respectively.
-
RFC+: Deterministic CBOR according to this specification
may also be provided in
Diagnostic Notation.
9. Version
Version: 1.0.3, 2023-12-05
undefined
and typed arrays beyondUint8Array
.