diff --git a/canonical-binary.md b/canonical-binary.md index 9ae6b60..f6b5462 100644 --- a/canonical-binary.md +++ b/canonical-binary.md @@ -21,41 +21,19 @@ This document specifies canonical form for the Preserves compact binary syntax. **General rules.** -Streaming formats ("format C") MUST NOT be used. -Annotations MUST NOT be present. -Placeholders MUST NOT be used. -Where possible, fixed-length ("format A") MUST be used in preference +Streaming formats ("format C") *MUST NOT* be used. +Annotations *MUST NOT* be present. +Placeholders *MUST NOT* be used. +Where possible, fixed-length ("format A") *MUST* be used in preference to variable-length ("format B") formats. -**Signed integers.** -When a `SignedInteger` *n* is greater than or equal to -3 and less -than 13 (i.e. -3≤*n*<13), it MUST be represented using the single-byte -encoding with initial nibble equal to 3. -Otherwise (i.e. when *n*<-3 or *n*≥13), it MUST be represented using -the multi-byte encoding with initial nibble equal to 4, and the -variable-length part must be as short as -possible.[^signed-integer-examples] - - [^signed-integer-examples]: The following examples from - [the specification][spec] are all in canonical form: - - [[ -257 ]] = 42 FE FF [[ -3 ]] = 3D [[ 128 ]] = 42 00 80 - [[ -256 ]] = 42 FF 00 [[ -2 ]] = 3E [[ 255 ]] = 42 00 FF - [[ -255 ]] = 42 FF 01 [[ -1 ]] = 3F [[ 256 ]] = 42 01 00 - [[ -254 ]] = 42 FF 02 [[ 0 ]] = 30 [[ 32767 ]] = 42 7F FF - [[ -129 ]] = 42 FF 7F [[ 1 ]] = 31 [[ 32768 ]] = 43 00 80 00 - [[ -128 ]] = 41 80 [[ 12 ]] = 3C [[ 65535 ]] = 43 00 FF FF - [[ -127 ]] = 41 81 [[ 13 ]] = 41 0D [[ 65536 ]] = 43 01 00 00 - [[ -4 ]] = 41 FC [[ 127 ]] = 41 7F [[ 131072 ]] = 43 02 00 00 - - **Sets.** -The elements of a `Set` MUST be serialized sorted in ascending order +The elements of a `Set` *MUST* be serialized sorted in ascending order following the total order relation defined in the [Preserves specification][spec]. **Dictionaries.** -The key-value pairs in a `Dictionary` MUST be serialized sorted in +The key-value pairs in a `Dictionary` *MUST* be serialized sorted in ascending order by key, following the total order relation defined in the [Preserves specification][spec].[^no-need-for-by-value] @@ -63,9 +41,9 @@ the [Preserves specification][spec].[^no-need-for-by-value] pair, since a `Dictionary` has no duplicate keys. **Other kinds of `Value`.** -There are no special canonicalization restrictions on `String`s, -`ByteString`s, `Symbol`s, `Boolean`s, `Float`s, `Double`s, `Record`s, -or `Sequence`s. +There are no special canonicalization restrictions on +`SignedInteger`s, `String`s, `ByteString`s, `Symbol`s, `Boolean`s, +`Float`s, `Double`s, `Record`s, or `Sequence`s. ## Notes diff --git a/preserves.md b/preserves.md index 29d7a29..0f25ef9 100644 --- a/preserves.md +++ b/preserves.md @@ -649,7 +649,8 @@ Integers in the range [-3,12] are compactly represented using format A because they are so frequently used. Other integers are represented using format B. -Format C *MUST NOT* be used for `SignedInteger`s. +Format C *MUST NOT* be used for `SignedInteger`s. Format A *MUST* be +used for integers in the range -3 to 12, inclusive. The function `intbytes(x)` gives the big-endian two's-complement binary representation of `x`, taking exactly as many whole bytes as