diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/std/json.md | 26 | ||||
| -rw-r--r-- | docs/std/slice.md | 93 | ||||
| -rw-r--r-- | docs/std/string.md | 4 |
3 files changed, 123 insertions, 0 deletions
diff --git a/docs/std/json.md b/docs/std/json.md index fba2ad8..ce35d64 100644 --- a/docs/std/json.md +++ b/docs/std/json.md @@ -51,6 +51,32 @@ Represents a node in a JSON document. - **`fn at(self, index: usize) -> Option<JsonValue*>`** Retrieves a value from an array by index. +#### Serialization + +- **`fn to_string(self) -> String`** + Serializes the JSON value to a string representation. + +- **`fn stringify(self, buf: String*)`** + Internal recursive serialization method that appends to a string buffer. + +**Example:** +```zc +let obj = JsonValue::object(); +obj.set("name", JsonValue::string("Alice")); +obj.set("age", JsonValue::number(30.0)); + +let json_str = obj.to_string(); +println "{json_str.c_str()}"; // {"name":"Alice","age":30} +json_str.free(); +obj.free(); +``` + +**Features:** +- Proper escaping of special characters: `\"`, `\\`, `\n`, `\t`, `\r`, `\b`, `\f` +- Numbers formatted with `%.15g` for precision +- Recursive serialization for nested objects and arrays +- Round-trip compatible with `parse()` + #### Memory Management - **`fn free(self)`** diff --git a/docs/std/slice.md b/docs/std/slice.md new file mode 100644 index 0000000..f029995 --- /dev/null +++ b/docs/std/slice.md @@ -0,0 +1,93 @@ +# Standard Library: Slice (`std/slice.zc`) + +`Slice<T>` is a lightweight, non-owning view into a contiguous sequence of elements. It's particularly useful for working with fixed-size arrays and enabling iteration. + +## Usage + +```zc +import "std/slice.zc" + +fn main() { + let arr: int[5] = [1, 2, 3, 4, 5]; + + // Direct iteration (auto-imports std/slice.zc) + for val in arr { + println "{val}"; + } + + // Manual slice creation + let slice = Slice<int>::from_array((int*)(&arr), 5); + for val in slice { + println "{val}"; + } +} +``` + +## Structure + +```zc +struct Slice<T> { + data: T*; + len: usize; +} +``` + +## Methods + +### Construction + +| Method | Signature | Description | +| :--- | :--- | :--- | +| **from_array** | `Slice<T>::from_array(arr: T*, len: usize) -> Slice<T>` | Creates a slice view over an array. | +| **new** | `Slice<T>::new(data: T*, len: usize) -> Slice<T>` | Alias for `from_array` (backwards compat). | + +### Iteration + +| Method | Signature | Description | +| :--- | :--- | :--- | +| **iterator** | `iterator(self) -> SliceIter<T>` | Returns an iterator for `for-in` loops. | + +`SliceIter<T>` implements the iterator protocol with a `next() -> Option<T>` method. + +### Access & Query + +| Method | Signature | Description | +| :--- | :--- | :--- | +| **length** | `length(self) -> usize` | Returns the number of elements. | +| **is_empty** | `is_empty(self) -> bool` | Returns true if length is 0. | +| **get** | `get(self, idx: usize) -> Option<T>` | Returns the element at index, or None if out of bounds. | +| **at** | `at(self, idx: usize) -> Option<T>` | Alias for `get`. | + +## Examples + +### Iterating over fixed-size arrays + +```zc +// std/slice.zc is auto-imported when using for-in on arrays +let numbers: int[3] = [10, 20, 30]; + +for n in numbers { + println "Number: {n}"; +} +``` + +### Safe indexed access + +```zc +import "std/slice.zc" + +let arr: int[3] = [1, 2, 3]; +let slice = Slice<int>::from_array((int*)(&arr), 3); + +let opt = slice.get(1); +if (!opt.is_none()) { + println "Value: {opt.unwrap()}"; // Prints: Value: 2 +} +``` + +## Notes + +- `Slice<T>` does not own its data — it's just a view +- No memory management needed (no `free()` method) +- **Auto-import**: `std/slice.zc` is automatically imported when using `for val in arr` on a fixed-size array +- The array pointer cast `(T*)(&arr)` is required for fixed-size arrays diff --git a/docs/std/string.md b/docs/std/string.md index 1f89e0f..a2f63f5 100644 --- a/docs/std/string.md +++ b/docs/std/string.md @@ -49,8 +49,12 @@ struct String { | Method | Signature | Description | | :--- | :--- | :--- | | **append** | `append(self, other: String*)` | Appends another string to this one. | +| **append_c** | `append_c(self, s: char*)` | Appends a C string literal. Uses value receiver. | +| **append_c_ptr** | `append_c_ptr(ptr: String*, s: char*)` | Appends a C string literal using pointer receiver for guaranteed mutation. | | **add** | `add(self, other: String*) -> String` | Concatenates this string and another into a new String. | +**Note:** When passing `String*` to functions that need to mutate, use `append_c_ptr` instead of `append_c` for reliable mutation. + ### Access & Query | Method | Signature | Description | |
