documentation

Author: jialinli98

README.md

@@ -85,6 +85,101 @@ fn process_schema(text: [u8; NUM_BYTES])
 }
 ```
 
+## Getters API
+
+#### Function name differences
+
+- **Checked vs Unchecked**
+  - `get_*`/`get_*_var` return `Option<T>`; use when a key or index may be absent.
+  - `get_*_unchecked`/`get_*_unchecked_var` return `T` and will error on missing/mismatched types.
+
+- **Fixed key vs Variable key**
+  - Functions taking `key: [u8; KeyBytes]` expect a fixed-length key known at compile time.
+  - Functions with `_var` take `key: BoundedVec<u8, KeyBytes>` for variable-length keys up to `KeyBytes`.
+
+### Object getters API
+
+- **`get_object<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSON>`**: From an object root, returns `Some(JSON)` if `key` exists and is an object, `None` if `key` is missing; errors if `key` exists but is not an object, or if called when the current root is an array.
+
+- **`get_object_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSON`**: From an object root, returns the object at `key`; errors otherwise.
+
+- **`get_object_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSON>`**: Same as `get_object`, but the key can be variable-length up to `KeyBytes`.
+
+- **`get_object_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSON`**: Same as `get_object_unchecked`, but with a variable-length key.
+
+- **`get_object_from_array(index: Field)` → `Option<JSON>`**: When the current root is an array, returns the object at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element is not an object.
+
+- **`get_object_from_array_unchecked(index: Field)` → `JSON`**: When the current root is an array, returns the object at `index`. Errors if `index` is out of bounds or the element is not an object.
+
+### Array getters API
+
+- **`get_length()` → `u32`**: Returns its length when the current root is an array; errors otherwise.
+
+- **`get_array<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSON>`**: From an object root, returns Some(JSON) if key exists and is an array, None if key is missing; errors if key exists but is not an array, or if called when the current root is an array.
+
+- **`get_array_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSON`**: From an object root, returns the array at key; errors otherwise.
+
+- **`get_array_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSON>`**: Same as `get_array`, but the key can be variable-length up to `KeyBytes`.
+
+- **`get_array_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSON`**: Same as `get_array_unchecked`, but with a variable-length key.
+
+- **`get_array_from_array(index: Field)` → `Option<JSON>`**: When the current root is an array, returns the nested array at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element is not an array.
+
+- **`get_array_from_array_unchecked(index: Field)` → `JSON`**: When the current root is an array, returns the nested array at `index`. Errors if `index` is out of bounds or the element is not an array.
+
+### Literal getters API
+
+Literals are the JSON keywords `true`, `false`, and `null`. They are represented by `JSONLiteral`, which supports:
+- `is_true()`, `is_false()`, `is_null()`
+- `to_bool()` (maps `true` → `true`, `false`/`null` → `false`)
+
+- **`get_literal<let KeyBytes>(key: [u8; KeyBytes])` → `Option<JSONLiteral>`**: From an object root, returns `Some(JSONLiteral)` if `key` exists and is a literal; `None` if `key` is missing; errors if `key` exists but is not a literal, or if called when the current root is an array.
+
+- **`get_literal_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `JSONLiteral`**: From an object root, returns the literal at `key`; errors if the key is missing, not a literal, or if called when the current root is an array.
+
+- **`get_literal_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<JSONLiteral>`**: Same as `get_literal`, but accepts a variable-length key up to `KeyBytes`.
+
+- **`get_literal_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `JSONLiteral`**: Same as `get_literal_unchecked`, with a variable-length key.
+
+- **`get_literal_from_array(index: Field)` → `Option<JSONLiteral>`**: When the current root is an array, returns the literal at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a literal.
+
+- **`get_literal_from_array_unchecked(index: Field)` → `JSONLiteral`**: When the current root is an array, returns the literal at `index`; errors if `index` is out of bounds or the element is not a literal.
+
+### Number getters API
+
+Numbers are parsed as unsigned integers and must fit into `u64` (no decimals).
+
+- **`get_number<let KeyBytes>(key: [u8; KeyBytes])` → `Option<u64>`**: From an object root, returns `Some(u64)` if `key` exists and is a number; `None` if `key` is missing; errors if `key` exists but is not a number, or if called when the current root is an array.
+
+- **`get_number_unchecked<let KeyBytes>(key: [u8; KeyBytes])` → `u64`**: From an object root, returns the number at `key`; errors if the key is missing, not a number, or if called when the current root is an array.
+
+- **`get_number_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<u64>`**: Same as `get_number`, but accepts a variable-length key up to `KeyBytes`.
+
+- **`get_number_unchecked_var<let KeyBytes>(key: BoundedVec<u8, KeyBytes>)` → `u64`**: Same as `get_number_unchecked`, with a variable-length key.
+
+- **`get_number_from_array(index: Field)` → `Option<u64>`**: When the current root is an array, returns the number at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a number.
+
+- **`get_number_from_array_unchecked(index: Field)` → `u64`**: When the current root is an array, returns the number at `index`; errors if `index` is out of bounds or the element is not a number.
+
+### String getters API
+
+Strings are returned as `BoundedVec<u8, StringBytes>` where `StringBytes` is the maximum allowed length of the returned string.
+
+- **`get_string<let KeyBytes, let StringBytes>(key: [u8; KeyBytes])` → `Option<BoundedVec<u8, StringBytes>>`**: From an object root, returns `Some(string)` if `key` exists and is a string; `None` if `key` is missing; errors if `key` exists but is not a string, or if called when the current root is an array.
+
+- **`get_string_unchecked<let KeyBytes, let StringBytes>(key: [u8; KeyBytes])` → `BoundedVec<u8, StringBytes>`**: From an object root, returns the string at `key`; errors otherwise.
+
+- **`get_string_var<let KeyBytes, let StringBytes>(key: BoundedVec<u8, KeyBytes>)` → `Option<BoundedVec<u8, StringBytes>>`**: Same as `get_string`, but accepts a variable-length key up to `KeyBytes`.
+
+- **`get_string_unchecked_var<let KeyBytes, let StringBytes>(key: BoundedVec<u8, KeyBytes>)` → `BoundedVec<u8, StringBytes>`**: Same as `get_string_unchecked`, with a variable-length key.
+
+- **`get_string_from_array<let StringBytes>(index: Field)` → `Option<BoundedVec<u8, StringBytes>>`**: When the current root is an array, returns the string at `index` wrapped in `Option`. Returns `None` if `index` is out of bounds; errors if in-bounds but the element at `index` is not a string.
+
+- **`get_string_from_array_unchecked<let StringBytes>(index: Field)` → `BoundedVec<u8, StringBytes>`**: When the current root is an array, returns the string at `index`; errors if `index` is out of bounds or the element is not a string.
+
+- **`get_string_from_path<let KeyBytes, let StringBytes, let PathDepth>(keys: [BoundedVec<u8, KeyBytes>; PathDepth])` → `Option<BoundedVec<u8, StringBytes>>`**: Traverses nested objects by the given keys; returns Some(string) if the final value exists and is a string, otherwise None.
+
+
 # Edge Cases
 
 ### single value JSON