std.json

Bytes.length and ByteBuffer.length are read-only int properties that report the number of bytes.

JSONValue.length is an Option<int> property. Arrays and objects return Some(count) for their element or member count. Other JSON kinds return None().

JSONValue.keys and JSONValue.values are properties returning Option<Array<string>> and Option<Array<JSONValue>>. Objects return Some(keys) or Some(values). Other JSON kinds return None().

Read these properties without parentheses, as with Array.length, Map.length, Map.keys, Map.values, and Set.length. Calling a property value is rejected as a non-callable value.

JSONValue.kind() -> string returns exactly one of null, bool, number, string, array, or object. The name describes the JSON value's outermost kind. Both true and false have kind bool. Integer and fractional JSON numbers have kind number.

Test whether a JSON value is null with value.kind() == "null". This comparison is false for false, zero, the empty string, and empty arrays and objects. Reading the kind does not modify or decode the JSON value.

A present array element or object member containing JSON null is still present. at and get return Some(value) containing that JSONValue. An absent element or member returns None(). Inspect presence first, then compare the contained value's kind.

JSONValue does not expose an isNull member. Use the same kind comparison for null as for every other JSON kind.

JSONValue is an immutable JSON tree with the six JSON kinds →. Reading a member preserves the tree.

asBool and asString return Some for the matching kind and None() for every other kind. False and empty text are present values. Neither function parses text or converts a number.

numberText returns the exact accepted number lexeme for a number and None() for another kind. It preserves a negative zero, exponent spelling and fractional trailing zeroes.

asInt returns Some for a number spelled as an optional minus and decimal integer digits within the signed 64 bit range. Negative zero becomes zero. A decimal point, exponent, overflow or different kind returns None() without rounding.

asArray returns the elements of an array in source order. Another kind returns None(). The returned array is a separate collection. Changing that collection does not change the JSON tree.

at uses a zero based array index. A negative index, an index at or beyond the array length, or a receiver of another kind returns None(). get uses an exact decoded object key and returns None() for an absent key or another receiver kind. A present null child is Some containing JSON null.

length is a property containing the array element count or object member count. Scalar kinds yield None(). keys and values are object properties. They contain arrays in ascending Unicode scalar order of decoded keys, with corresponding positions. Array and scalar receivers yield None() for both properties.

The receiver and supplied arguments are evaluated once in ordinary call order. Inspection performs no I/O and invokes no user conversion. Incorrect argument types follow ordinary checking diagnostics rather than becoming absent values.

parse accepts one complete JSON value with leading and trailing space, tab, CR or LF. An empty input, a byte order mark, comments, trailing commas and trailing nonwhitespace return Err. Scalars are valid roots.

JSON numbers follow the JSON decimal grammar. A leading plus, redundant leading zero, missing fraction or exponent digits, NaN and infinities are invalid. Every accepted lexeme is stored exactly without conversion to binary floating point. Its magnitude need not fit int or float.

Quoted strings decode the JSON escapes and valid UTF 16 surrogate pairs into Unicode scalar values. Unescaped controls, malformed escapes and unpaired surrogates return Err. No Unicode normalization is performed.

Object names are compared after escape decoding. A repeated name returns Err before its value is converted into the object. The second name does not overwrite the first. Arrays preserve source order and object traversal follows the decoded key order →.

The root starts at depth zero. Descending into an array element or object value adds one. Depths through 128 are accepted and the first value at depth 129 returns Err with a nesting limit message.

A parse failure returns a record containing a nonempty cause message and one based line and column integers. Columns count Unicode scalar values. CRLF is one line break and a lone CR or LF also starts the next line. The first offending scalar is the location. An invalid escape points to its backslash. A repeated name points to its second opening quote. An incomplete input points immediately after the final scalar.

The text expression is evaluated once before parsing. The parser consumes through trailing whitespace before returning Ok. It performs no I/O, invokes no typed decoder and exposes no partial tree. Malformed data uses the Result error channel rather than a runtime diagnostic.

stringify requires the JSON conformance of its input type. It calls JSON.encode once and writes the returned JSON tree. A type without that conformance is rejected during checking with TPZ5533. The protocol representation rules define records, enums, arrays, maps, options, results and custom codecs.

Successful output contains one compact JSON value with no leading whitespace or terminal newline. Object names follow the decoded key order →. Arrays retain their element order. Map insertion order and record declaration order do not choose serialization order.

The writer escapes quotation marks and backslashes. It uses the short escapes for LF, CR and tab. Other controls below U+0020 use four digit lowercase Unicode escapes. Other scalar values are emitted unchanged. It does not escape a slash or normalize Unicode.

An existing JSONValue retains every accepted number lexeme. An int uses decimal digits and an optional minus. Float encoding follows JSON numeric conversion →, including its shortest binary64 roundtrip spelling and negative zero. NaN and infinities return Err.

The depth and active value cycle rules of JSON conversion apply. A depth above 128 or a value cycle returns an error beginning JSON_LIMIT. Other value failures return the selected codec error. Built in conversion errors identify the first failing child with a path rooted at $.

The input expression is evaluated before conversion. Built in conversions visit arrays in index order and objects in sorted key order. A custom encoder retains its ordinary evaluation and side effects. An encoder error prevents writing. This function returns text and performs no filesystem or stream write.

parseAs<T> requires an explicit JSON decodable result type. The ordinary JSON capability checks apply. Omitting a required result type or selecting a type without decoding support produces TPZ5534.

The function completes JSON parsing → before calling JSON.decode<T>. A malformed document returns an error string containing the parse cause, line and column. It never calls the decoder on a malformed or trailing input.

After parsing succeeds, the selected decoder is called once. Its Ok payload or Err message becomes the result. Custom decoder effects occur after parsing and follow ordinary function evaluation. Built in decoding performs no I/O.

The JSON protocol defines supported representations. Derived records ignore unknown fields and use declared defaults for missing fields. A missing required field, wrong kind, unknown enum tag, wrong payload count or value outside the target numeric range returns Err. No string to number or string to boolean coercion is performed.

Built in errors describe the expected shape and first failing path rooted at $. Arrays are checked in increasing index order and object fields in ascending Unicode scalar order. Built in int decoding requires an exactly integral value within signed 64 bit bounds. Float decoding follows the protocol rounding and overflow rules. Optional null and nested option normalization follow the same protocol rule as JSON.decode. Use numberText and asInt when the input must retain the integer spelling boundary.

Decode an already parsed tree with JSON.decode<T>. There is no second JSONValue receiver decoding form. Parsing failure and decoding failure are recoverable Result errors and do not produce assertion diagnostics by themselves.