summaryrefslogtreecommitdiff
path: root/docs/std
diff options
context:
space:
mode:
Diffstat (limited to 'docs/std')
-rw-r--r--docs/std/README.md6
-rw-r--r--docs/std/json.md57
-rw-r--r--docs/std/net.md44
-rw-r--r--docs/std/set.md38
-rw-r--r--docs/std/stack.md38
-rw-r--r--docs/std/thread.md47
-rw-r--r--docs/std/time.md38
7 files changed, 268 insertions, 0 deletions
diff --git a/docs/std/README.md b/docs/std/README.md
index 6125a4e..16ffc74 100644
--- a/docs/std/README.md
+++ b/docs/std/README.md
@@ -3,10 +3,16 @@
- [Env (Environment)](./env.md) - Process environment variables.
- [File System (FS)](./fs.md) - File I/O and directory operations.
- [IO](./io.md) - Standard Input/Output.
+- [JSON](./json.md) - JSON parsing and serialization.
- [Map](./map.md) - Hash map implementation.
+- [Networking (Net)](./net.md) - TCP networking.
- [Option](./option.md) - Optional values (Some/None).
- [Path](./path.md) - File path manipulation.
- [Result](./result.md) - Error handling (Ok/Err).
- [Queue](./queue.md) - FIFO queue (Ring Buffer).
+- [Set](./set.md) - Hash set implementation.
+- [Stack](./stack.md) - LIFO stack.
- [String](./string.md) - Growable, heap-allocated string type.
+- [Thread (Concurrency)](./thread.md) - Multithreading and synchronization.
+- [Time](./time.md) - Time measurement and sleep.
- [Vector (Vec)](./vec.md) - A growable dynamic array.
diff --git a/docs/std/json.md b/docs/std/json.md
new file mode 100644
index 0000000..fba2ad8
--- /dev/null
+++ b/docs/std/json.md
@@ -0,0 +1,57 @@
+# JSON (`std/json.zc`)
+
+The `std/json` module provides a DOM-style JSON parser and builder.
+
+## Usage
+
+```zc
+import "std/json.zc"
+```
+
+## Types
+
+### Struct `JsonValue`
+
+Represents a node in a JSON document.
+
+#### Creation Methods
+
+- **`fn null() -> JsonValue`**, **`fn null_ptr() -> JsonValue*`**
+- **`fn bool(b: bool) -> JsonValue`**, **`fn bool_ptr(b: bool) -> JsonValue*`**
+- **`fn number(n: double) -> JsonValue`**, **`fn number_ptr(n: double) -> JsonValue*`**
+- **`fn string(s: char*) -> JsonValue`**, **`fn string_ptr(s: char*) -> JsonValue*`**
+- **`fn array() -> JsonValue`**, **`fn array_ptr() -> JsonValue*`**
+- **`fn object() -> JsonValue`**, **`fn object_ptr() -> JsonValue*`**
+
+#### Parsing
+
+- **`fn parse(json: char*) -> Result<JsonValue*>`**
+ Parses a JSON string into a heap-allocated `JsonValue` tree.
+
+#### Accessors
+
+- **`fn is_null(self) -> bool`**, **`is_bool`**, **`is_number`**, **`is_string`**, **`is_array`**, **`is_object`**
+ Check the type of the value.
+
+- **`fn as_string(self) -> Option<char*>`**
+ Returns `Some(string)` if the value is a string, `None` otherwise.
+- **`fn as_int(self) -> Option<int>`**
+- **`fn as_float(self) -> Option<double>`**
+- **`fn as_bool(self) -> Option<bool>`**
+
+#### Object/Array Operations
+
+- **`fn push(self, val: JsonValue)`**
+ Appends a value to an array.
+- **`fn set(self, key: char*, val: JsonValue)`**
+ Sets a key-value pair in an object.
+
+- **`fn get(self, key: char*) -> Option<JsonValue*>`**
+ Retrieves a value from an object by key.
+- **`fn at(self, index: usize) -> Option<JsonValue*>`**
+ Retrieves a value from an array by index.
+
+#### Memory Management
+
+- **`fn free(self)`**
+ Recursively frees the JSON value and all its children.
diff --git a/docs/std/net.md b/docs/std/net.md
new file mode 100644
index 0000000..392c901
--- /dev/null
+++ b/docs/std/net.md
@@ -0,0 +1,44 @@
+# Networking (`std/net.zc`)
+
+The `std/net` module provides basic TCP networking capabilities.
+
+## Usage
+
+```zc
+import "std/net.zc"
+```
+
+## Types
+
+### Type `TcpListener`
+
+Represents a TCP socket listening for incoming connections.
+
+#### Methods
+
+- **`fn bind(host: char*, port: int) -> Result<TcpListener>`**
+ Creates a new listener bound to the specified host and port.
+
+- **`fn accept(self) -> Result<TcpStream>`**
+ Blocks waiting for a new connection. Returns a `TcpStream` for the connected client.
+
+- **`fn close(self)`**
+ Closes the listening socket.
+
+### Type `TcpStream`
+
+Represents a TCP connection stream.
+
+#### Methods
+
+- **`fn connect(host: char*, port: int) -> Result<TcpStream>`**
+ Connects to a remote host.
+
+- **`fn read(self, buf: char*, len: usize) -> Result<usize>`**
+ Reads up to `len` bytes into `buf`. Returns the number of bytes read.
+
+- **`fn write(self, buf: char*, len: usize) -> Result<usize>`**
+ Writes `len` bytes from `buf` to the stream. Returns the number of bytes written.
+
+- **`fn close(self)`**
+ Closes the connection.
diff --git a/docs/std/set.md b/docs/std/set.md
new file mode 100644
index 0000000..0d62a66
--- /dev/null
+++ b/docs/std/set.md
@@ -0,0 +1,38 @@
+# Set (`std/set.zc`)
+
+The `std/set` module provides a Generic Hash Set `Set<T>`.
+
+## Usage
+
+```zc
+import "std/set.zc"
+```
+
+## Types
+
+### Struct `Set<T>`
+
+A set of unique elements.
+
+#### Methods
+
+- **`fn new() -> Set<T>`**
+ Creates a new empty set.
+
+- **`fn add(self, val: T) -> bool`**
+ Adds a value to the set. Returns `true` if the value was added, `false` if it was already present.
+
+- **`fn contains(self, val: T) -> bool`**
+ Returns `true` if the set contains the value.
+
+- **`fn remove(self, val: T) -> bool`**
+ Removes a value from the set. Returns `true` if present and removed.
+
+- **`fn length(self) -> usize`**
+ Returns the number of elements in the set.
+
+- **`fn is_empty(self) -> bool`**
+ Returns `true` if the set is empty.
+
+- **`fn clear(self)`**
+ Removes all elements from the set.
diff --git a/docs/std/stack.md b/docs/std/stack.md
new file mode 100644
index 0000000..6e5da84
--- /dev/null
+++ b/docs/std/stack.md
@@ -0,0 +1,38 @@
+# Stack (`std/stack.zc`)
+
+The `std/stack` module provides a LIFO (Last-In, First-Out) stack data structure.
+
+## Usage
+
+```zc
+import "std/stack.zc"
+```
+
+## Types
+
+### Struct `Stack<T>`
+
+A generic stack.
+
+#### Methods
+
+- **`fn new() -> Stack<T>`**
+ Creates a new empty stack.
+
+- **`fn push(self, value: T)`**
+ Pushes a value onto the top of the stack.
+
+- **`fn pop(self) -> Option<T>`**
+ Removes and returns the top element of the stack. Returns `None` if empty.
+
+- **`fn length(self) -> usize`**
+ Returns the number of elements in the stack.
+
+- **`fn is_empty(self) -> bool`**
+ Returns `true` if the stack contains no elements.
+
+- **`fn clear(self)`**
+ Removes all elements from the stack.
+
+- **`fn clone(self) -> Stack<T>`**
+ Creates a deep copy of the stack.
diff --git a/docs/std/thread.md b/docs/std/thread.md
new file mode 100644
index 0000000..6ac7e29
--- /dev/null
+++ b/docs/std/thread.md
@@ -0,0 +1,47 @@
+# Concurrency (`std/thread.zc`)
+
+The `std/thread` module provides primitives for multithreading and synchronization.
+
+## Usage
+
+```zc
+import "std/thread.zc"
+```
+
+## Functions
+
+- **`fn sleep_ms(ms: int)`**
+ Sleeps the current thread for the specified number of milliseconds.
+
+## Types
+
+### Type `Thread`
+
+Represents a handle to a spawned thread.
+
+#### Methods
+
+- **`fn spawn(func: fn()) -> Result<Thread>`**
+ Spawns a new thread executing the provided function.
+ > Note: Currently supports void functions with no arguments.
+
+- **`fn join(self) -> Result<bool>`**
+ Blocks the current thread until the spawned thread finishes.
+
+### Type `Mutex`
+
+A mutual exclusion primitive for protecting shared data.
+
+#### Methods
+
+- **`fn new() -> Mutex`**
+ Creates a new mutex.
+
+- **`fn lock(self)`**
+ Acquires the lock. Blocks if the lock is already held.
+
+- **`fn unlock(self)`**
+ Releases the lock.
+
+- **`fn free(self)`**
+ Destroys the mutex and frees associated resources.
diff --git a/docs/std/time.md b/docs/std/time.md
new file mode 100644
index 0000000..97dd208
--- /dev/null
+++ b/docs/std/time.md
@@ -0,0 +1,38 @@
+# Time (`std/time.zc`)
+
+The `std/time` module provides functionality for measuring time and sleeping.
+
+## Usage
+
+```zc
+import "std/time.zc"
+```
+
+## Structs
+
+### Struct `Duration`
+
+Represents a span of time in milliseconds.
+
+#### Methods
+
+- **`fn from_ms(ms: U64) -> Duration`**
+ Creates a duration from milliseconds.
+
+- **`fn from_secs(s: U64) -> Duration`**
+ Creates a duration from seconds.
+
+### Struct `Time`
+
+Utilities for time manipulation.
+
+#### Methods
+
+- **`fn now() -> U64`**
+ Returns the current system time in milliseconds since the epoch.
+
+- **`fn sleep(d: Duration)`**
+ Sleeps for the specified duration.
+
+- **`fn sleep_ms(ms: U64)`**
+ Sleeps for the specified number of milliseconds.