docs(strings): Add ns_string documentation

- Added a doc about Small String Optimization (SSO)
- Docs on how to initialize strings using `ns_string`
- Docs on how to concatenate strings using `ns_string_concat()` function

Signed-off-by: Vaishnav Sabari Girish <vaishnav.sabari.girish@gmail.com>

Author: Vaishnav-Sabari-Girish

src/SUMMARY.md

@@ -24,6 +24,10 @@
   - [Creating & Freeing Strings](string/lifecycle.md)
   - [String Concatenation](string/concatenation.md)
 
+- [Data Structures (`ns_data`)](data_structures/README.md)
+  - [Dynamic Arrays (`ns_vec`)](data_structures/vectors.md)
+  - [Key-Value Maps (`ns_hashmap`)](data_structures/hashmap.md)
+
 - [Examples](examples/README.md)
   - [Safe User Input](examples/safe-input.md)
   - [Building a CLI Menu](examples/cli-menu.md)

src/data_structures/README.md

@@ -1 +1,42 @@
-# Strings (ns_string)
+# Strings (`ns_string`)
+
+In standard C, a string is nothing more than a contiguous array of characters in
+memory, terminated by a null byte (`\0`).
+
+While this design is incredibly minimalist, it is also the root cause of
+countless security vulnerabilities. Because standard C strings do not inherently
+know their own length or capacity, functions like `strcpy` and `strcat` will
+happily overwrite adjacent memory if the destination buffer is too small,
+leading to catastrophic **buffer overflows**.
+
+Furthermore, simply finding the length of a standard C string using `strlen()`
+requires an `O(N)` operation—scanning every single byte until the null
+terminator is found.
+
+## The NextStd Solution
+
+The `ns_string` module introduces a radically different approach. Instead of raw
+character pointers, NextStd strings are intelligent structs managed safely by
+the Rust backend.
+
+By tracking their own length and capacity, NextStd strings make out-of-bounds
+writes architecturally impossible. If you try to append text that exceeds the
+current capacity, the Rust backend will automatically and safely reallocate the
+heap memory for you.
+
+Even better, `ns_string` implements **Small String Optimization (SSO)**. This
+means short strings avoid the slow, expensive heap allocation process entirely
+and are stored directly on the stack, delivering blistering performance that
+rivals or beats standard C arrays.
+
+## What's in this chapter?
+
+This chapter breaks down how to create, manage, and manipulate memory-safe
+strings:
+
+- **[SSO Architecture](sso-architecture.md):** Look under the hood at how
+  NextStd avoids heap allocations for short strings to maximize performance.
+- **[String Lifecycle](lifecycle.md):** Learn how to initialize, read, and
+  safely free `ns_string` objects.
+- **[Concatenation & Manipulation](concatenation.md):** Discover how to safely
+  append and modify strings without ever worrying about buffer overflows again.

src/data_structures/hashmap.md

@@ -1 +1,76 @@
-# String Concatenation
+# String Concatenation (`ns_string_concat`)
+
+In standard C, appending text to a string using `strcat` is one of the most
+dangerous operations you can perform.
+
+If the destination buffer doesn't have enough pre-allocated space to hold both
+the original string and the new text, `strcat` will silently overwrite adjacent
+memory. This leads to data corruption, mysterious crashes, and severe security
+vulnerabilities.
+
+`NextStd` eliminates this entirely with memory-safe concatenation.
+
+## Safe Concatenation
+
+With `NextStd`, you never have to manually calculate buffer sizes. Instead of
+mutating an existing string, the `ns_string_concat` function takes two source
+`ns_string` objects and safely writes the combined text into a brand new
+destination `ns_string`.
+
+Because combining two strings might require allocating memory on the heap (which
+can technically fail if the system is out of memory), it returns an `ns_error_t`
+that you should wrap in an `NS_TRY` block.
+
+```c
+#include <nextstd/ns.h>
+
+int main() {
+    ns_error_t err;
+    ns_string s1, s2, result;
+
+    // 1. Initialize the source strings
+    NS_TRY(err, ns_string_new(&s1, "Hello, ")) {
+    } NS_EXCEPT(err, NS_ERROR_ANY) { return 1; }
+
+    NS_TRY(err, ns_string_new(&s2, "memory safety!")) {
+    } NS_EXCEPT(err, NS_ERROR_ANY) { return 1; }
+
+    // 2. Safely concatenate them into the 'result' string
+    NS_TRY(err, ns_string_concat(&result, s1, s2)) {
+        ns_println("Concatenation successful!");
+    } NS_EXCEPT(err, NS_ERROR_ANY) {
+        ns_print("Failed to concatenate: ");
+        ns_println(ns_error_message(err));
+        return 1;
+    }
+
+    // 3. Print the combined result
+    ns_print("Final message: ");
+    ns_println(result);
+
+    // 4. Always clean up all strings!
+    ns_string_free(&s1);
+    ns_string_free(&s2);
+    ns_string_free(&result);
+
+    return 0;
+}
+```
+
+## How It Works (The SSO Transition)
+
+When you call `ns_string_concat`, the Rust backend performs a series of safety
+checks to determine exactly how the new `result` string should be constructed:
+
+1. **Capacity Calculation:** It adds the `len` of `s1` and `s2` together to find
+   the exact required size.
+2. **The SSO Decision:** If the combined length is under 24 bytes, the `result`
+   string will utilize **Small String Optimization (SSO)** and live entirely on
+   the stack. Zero heap allocations occur!
+3. **Dynamic Reallocation:** If the combined length is 24 bytes or larger, the
+   Rust backend safely allocates a new buffer on the heap, copies the data from
+   both source strings into it, and flags the `result` struct as `is_heap`.
+
+This entire memory management process happens invisibly. From the C side, you
+just call `ns_string_concat`, and `NextStd` guarantees it succeeds safely or
+returns a catchable error!

src/data_structures/vectors.md

@@ -1 +1,109 @@
-# Creating & Freeing Strings
+# Creating & Freeing Strings
+
+Unlike standard C strings, which are often just raw pointers to arbitrary blocks
+of memory, an `ns_string` is a fully managed data structure.
+
+To guarantee memory safety and prevent undefined behavior, every `ns_string`
+must go through a strict, three-step lifecycle: **Initialization**, **Usage**,
+and **Destruction**.
+
+## 1. Initialization (`ns_string_new`)
+
+Before you can use an `ns_string`, it must be initialized. You do this by
+passing a pointer to your uninitialized `ns_string` struct and the initial
+standard C string (or `""` for an empty string) to the `ns_string_new` function.
+
+This is where the Rust backend takes over. It calculates the length of your
+input, decides whether to store it on the stack (via Small String Optimization)
+or allocate memory on the heap, and populates your struct safely.
+
+```c
+#include <nextstd/ns.h>
+
+int main() {
+    ns_error_t err;
+    ns_string my_text;
+
+    // 1. Initialize the string
+    NS_TRY(err, ns_string_new(&my_text, "Welcome to NextStd!")) {
+        ns_println("String initialized successfully.");
+    } NS_EXCEPT(err, NS_ERROR_ANY) {
+        ns_println("Failed to allocate string.");
+        return 1;
+    }
+
+    // ... usage and destruction ...
+    return 0;
+}
+```
+
+## 2. Usage
+
+Once initialized, your `ns_string` struct contains safely managed properties.
+Because it utilizes Small String Optimization (SSO), the underlying text data is
+safely tucked away inside a union.
+
+Fortunately, you don't have to manually extract it. Because `ns_print` and
+`ns_println` handle `ns_string` objects natively via C11 `_Generic` macros, you
+can simply pass the entire struct directly to print your managed string!
+
+```c
+    // 2. Use the string
+    ns_print("Message: ");
+    ns_println(my_text); // No need to access inner pointers!
+```
+
+## 3. Destruction (`ns_string_free`)
+
+Standard C requires you to manually call `free()` on any memory you allocate. If
+you forget, your program leaks memory. If you call it twice, your program
+crashes (a "double free" vulnerability).
+
+When you are finished with an `ns_string`, you **must** pass its pointer to
+`ns_string_free`.
+
+```c
+    // 3. Destroy the string
+    ns_string_free(&my_text);
+```
+
+The Rust backend handles the deallocation process intelligently. If the string
+was utilizing Small String Optimization (stored entirely on the stack),
+`ns_string_free` does practically nothing, safely avoiding an invalid heap
+operation. If it was allocated on the heap, Rust cleanly returns the memory to
+the system and nullifies the pointers to prevent accidental use-after-free
+vulnerabilities.
+
+---
+
+### The Complete Example
+
+Putting it all together, here is the complete, memory-safe lifecycle of an
+`ns_string`:
+
+```c
+#include <nextstd/ns.h>
+
+int main() {
+    ns_error_t err;
+    ns_string greeting;
+
+    // 1. Initialization
+    NS_TRY(err, ns_string_new(&greeting, "Hello, memory safety!")) {
+
+        // 2. Usage
+        ns_print("The string is: ");
+        ns_println(greeting); // Magically works!
+
+    } NS_EXCEPT(err, NS_ERROR_ANY) {
+        ns_print("Error: ");
+        ns_println(ns_error_message(err));
+        return 1;
+    }
+
+    // 3. Destruction (Always clean up!)
+    ns_string_free(&greeting);
+
+    return 0;
+}
+```

src/string/README.md

@@ -1 +1,57 @@
 # Small String Optimization (SSO)
+
+In standard C, if you want a string that can grow dynamically, you have to use
+`malloc()` to allocate memory on the heap.
+
+The problem is that heap allocations are notoriously slow. Requesting memory
+from the operating system, finding a contiguous block, and managing pointers
+adds significant overhead. If you are processing thousands of short strings—like
+parsing names, IP addresses, or configuration keys—this heap allocation
+bottleneck will severely degrade your application's performance.
+
+NextStd solves this elegantly using a technique called
+**Small String Optimization (SSO)**.
+
+## How SSO Works
+
+The core idea behind SSO is simple: **Why ask the OS for memory if the string is
+small enough to fit inside the struct itself?**
+
+When you initialize an `ns_string`, the Rust backend checks the length of the
+text you are trying to store.
+
+1. **The Stack Path (Short Strings):** If the string is short (typically under
+   15-23 characters, depending on the system architecture), NextStd stores the
+   characters *directly inside* the `ns_string` struct on the stack. Zero heap
+   allocations are performed.
+2. **The Heap Path (Long Strings):** If the string exceeds the inline capacity,
+   NextStd automatically falls back to allocating space on the heap and stores a
+   pointer to that data inside the struct.
+
+## The Performance Impact
+
+Because most strings in typical applications are short, SSO provides a massive
+performance boost:
+
+* **Zero Allocation Cost:** Creating and destroying short strings is practically
+  instantaneous.
+* **Cache Locality:** Because the string data lives directly inside the struct
+  on the stack, the CPU can read it without having to jump across RAM to chase a
+  heap pointer. This heavily optimizes CPU cache hits.
+* **Safe Fallback:** You never have to manually decide between a fixed-size
+  stack array (which risks buffer overflows) and a dynamic heap pointer. The
+  `ns_string` handles the transition invisibly.
+
+## Invisible to the User
+
+The best part about NextStd's SSO implementation is that you don't have to think
+about it.
+
+Whether your string is 5 characters long and living on the stack, or 50,000
+characters long and living on the heap, the C API remains exactly the same. You
+still call `ns_string_new` to create it, read from its `data` pointer, and call
+`ns_string_free` when you are done.
+
+The Rust backend tracks the memory state internally and guarantees that when
+`ns_string_free` is called, it won't accidentally try to `free()` a
+stack-allocated string, completely preventing invalid free crashes.