Capy-Bearer Documentation

Description

Options default to pretty: false, indent: 2, and ascii_only: false. Omitted options and none use the defaults and preserve the default output bytes. Unknown fields are ignored. Options must be none or an explicit map, not a list or scalar.

pretty must be a boolean. When true, nonempty arrays and objects use newlines, indentation, a space after each colon, and a newline after each comma. Closing brackets and braces use the containing value's indentation. Empty arrays and objects stay [] and {}.

indent must be an integer from 0 through 16. It sets the number of spaces per level. Zero keeps the newlines without indentation. Invalid indentation fails even when pretty is false.

ascii_only must be a boolean. When true, non-ASCII characters use lowercase hexadecimal \uXXXX escapes. Characters above U+FFFF use surrogate pairs. This applies to strings and object keys. Invalid raw UTF-8 fails encoding when ascii_only is true. Controls, quotes, and backslashes always use JSON escapes. By default, Unicode characters, including U+2028 and U+2029, remain literal.

Invalid recognized option types or values return an empty string, without an exception. Neither the value nor the options map changes.

json_encode() emits signed and unsigned integer values as exact decimal numeric tokens across their full 64-bit ranges. It encodes finite f64 values with round-trip binary64 precision. Nested numbers use the same precision and can use exponent notation. Nonfinite values become JSON null. Strings remain strings, including numeric text. A none value becomes JSON null. Strings and object keys escape all control bytes.

Use json_decode(text) for JSON input and see its numeric-range contract. These functions preserve map insertion order, but not whitespace or number spelling. Use BRRB when integer kinds must also survive serialization.

Empty maps and empty lists remain distinct. Numeric-looking object keys remain map keys, including sequential keys from "0". Maps retain insertion order through encoding and decoding. Use sort(map) explicitly for lexical key order.

Cycles, values beyond the BRRB nesting or node limits, and unsupported nodes cause the complete encoding to fail. Opaque handles and callables are unsupported. Failure returns an empty string, not partial JSON or a null replacement. A valid empty JSON string encodes as "". This API does not expose a structured encoding error.

JSON does not preserve shared references.