Revise array safety docs site

Author: code5717

README.md

@@ -8,21 +8,25 @@ Lightweight macro helpers for dynamic arrays in C with safer edge-case handling
 generate_array_type(int);
 ```
 
-This creates `Array(int)` and `Slice(int)`.
+This creates `Array(int)`, `Slice(int)`, and `Span(int)`.
 
 ## API safety tiers
 
 Use checked macros by default. Keep unchecked macros only for compatibility or explicitly performance-focused paths where preconditions are guaranteed.
 
 ## Checked APIs (recommended)
 
-- `array_make(T, size)`: allocate array with initial capacity (`size` can be `0`).
+- `array_make(T, size)`: allocate array with initial capacity; use `8` as a practical default when size is unknown (`0` is allowed when you want no spare slots).
 - `array_free(arr)`: free array memory.
 - `array_reserve(arr, min_capacity)`: ensure capacity, returns `bool` and may update `arr` after `realloc`.
-- `array_try_push(arr, value)`: append scalar rvalues, returns `bool`.
-- `array_try_push_lvalue(arr, value)`: append struct or other non-scalar elements, returns `bool`.
-- `array_try_at(arr, idx, out_ptr)`: bounds-checked access; writes a pointer into the array, returns `bool`.
-- `array_try_slice_t(T, arr, low, high, out_slice)`: bounds-checked slice creation, returns `bool`.
+- `array_try_push(arr, value)`: append an element, returns `bool`.
+- `array_try_push_lvalue(arr, value)`: compatibility alias for `array_try_push`.
+- `array_try_at(arr, idx, out_ptr)`: bounds-checked temporary pointer access, returns `bool`.
+- `array_try_get(arr, idx, out_value)`: bounds-checked copy access, returns `bool`.
+- `array_try_set(arr, idx, value)`: bounds-checked assignment, returns `bool`.
+- `array_try_slice_t(T, arr, low, high, out_slice)`: bounds-checked range slice creation, returns `bool`.
+- `array_try_slice_at_t(T, arr, slice, idx, out_ptr)`: bounds-checked temporary pointer access through a slice range.
+- `array_try_span_t(T, arr, slice, out_span)`: materialize a temporary borrowed pointer span from a current array and slice range.
 - `array_back_ptr(arr)`: pointer to last element or `NULL` when empty.
 - `array_length(arr)`: element count.
 - `array_is_empty(arr)`: true if `count == 0`.
@@ -38,12 +42,13 @@ These are kept for compatibility and speed-focused code paths:
 - `array_at(arr, idx)`: unchecked index access.
 - `array_end(arr)`: unchecked last-element pointer (invalid on empty arrays).
 - `array_end_unchecked(arr)`: explicit unchecked alias.
-- `slice_from_array_t(T, arr, low, high)`: unchecked slice creation.
+- `slice_from_array_t(T, arr, low, high)`: unchecked range slice creation.
+- `span_make_t(T, elements, count)`: unchecked borrowed pointer span creation.
 
 ## Portability notes
 
-- Strict C11/C17 path (`-std=c11 -pedantic`): `ARRAY_HAS_TYPEOF` is `0`; use `array_for_each_t(T, arr, it)` and typed slice macros.
-- GNU/Clang convenience path: `ARRAY_HAS_TYPEOF` is `1`; `array_for_each(arr, it)` and `slice_from_array` are available.
+- Strict C11/C17 path (`-std=c11 -pedantic`): `ARRAY_HAS_TYPEOF` is `0`; use `array_for_each_t(T, arr, it)` and typed slice/span macros.
+- GNU/Clang convenience path: `ARRAY_HAS_TYPEOF` is `1`; `array_for_each(arr, it)`, `slice_from_array`, and `span_make` are available.
 
 ## Compile verification
 
@@ -63,7 +68,7 @@ generate_array_type(int);
 
 int main(void)
 {
-    Array(int) values = array_make(int, 0);
+    Array(int) values = array_make(int, 8);
     int *at0 = NULL;
 
     if (!values) return 1;
@@ -88,10 +93,13 @@ int main(void)
 ## Edge-case behavior
 
 - Zero-capacity arrays grow correctly on first push.
+- `array_make(T, 8)` is the recommended starting point for ordinary small/unknown lists; pass a better estimate when you have one.
 - Allocation/growth arithmetic is overflow-checked.
 - Reallocation failures do not discard existing array data.
 - `array_try_slice_t` rejects invalid ranges (`low > high` or `high > count`).
-- `array_try_at` and `array_try_slice_t` return `false` when output pointers are `NULL`.
+- Checked APIs return `false` when required output pointers are `NULL`.
+- `Slice(T)` stores a range and does not dangle merely because backing storage moved.
+- `Span(T)` and element pointers are temporary borrowed views and become invalid after backing storage is freed or reallocated.
 
 ## Documentation