Docs

.claude/util.md

@@ -0,0 +1,162 @@
+# Utilities
+
+Source: `src/dusk/util/`
+
+---
+
+## String (`util/string.h`)
+
+**Always use these instead of stdlib equivalents** (`strcmp`, `strcpy`, `sprintf`, etc.).
+
+```c
+stringCopy(dest, src, destSize);           // safe strncpy; always null-terminates
+stringCompare(a, b);                       // -1 / 0 / 1
+stringEquals(a, b);                        // bool_t
+stringCompareInsensitive(a, b);            // case-insensitive -1 / 0 / 1
+stringTrim(str);                           // in-place strip leading/trailing whitespace
+stringFindLastChar(str, c);                // last occurrence pointer or NULL
+stringFormat(dest, destSize, fmt, ...);    // snprintf wrapper; pass NULL dest to get length
+stringFormatVA(dest, destSize, fmt, args); // va_list version
+
+stringIsWhitespace(c);                     // bool_t
+
+// Parse:
+stringToI32(str, &out)   → bool_t
+stringToI64(str, &out)   → bool_t
+stringToI16(str, &out)   → bool_t
+stringToU16(str, &out)   → bool_t
+stringToF32(str, &out)   → bool_t
+
+// Suffix checks:
+stringEndsWith(str, suffix)                 → bool_t
+stringEndsWithCaseInsensitive(str, suffix)  → bool_t
+stringIncludesString(haystack, needle)      → bool_t
+```
+
+---
+
+## Memory (`util/memory.h`)
+
+**Always use these instead of `malloc`/`free`/`memcpy`/`memset` directly.**
+
+```c
+memoryAllocate(size)          → void *      // malloc + tracks pointer count
+memoryAlign(alignment, size)  → void *      // aligned malloc
+memoryFree(ptr)                             // free + decrements count
+memoryReallocate(&ptr, size)               // realloc
+memoryResize(&ptr, oldSize, newSize)       // realloc + copy (safe reshape)
+memoryTrack(ptr)                           // track externally-malloc'd pointer
+
+memoryCopy(dest, src, size)                // memcpy
+memoryMove(dest, src, size)                // memmove
+memorySet(dest, value, size)               // memset
+memoryZero(dest, size)                     // memset 0
+memoryCompare(a, b, size)     → int_t      // memcmp
+
+// Useful for uploading vertex data with different source/dest layouts:
+memoryCopyInterleaved(dest, destStride, src, srcStride, elementSize, count);
+memoryCopyRangeSafe(dest, start, end, sizeMax);  // copy with bounds check
+
+memoryGetAllocatedCount()     → size_t     // current malloc'd block count
+```
+
+---
+
+## Math (`util/math.h`)
+
+```c
+mathNextPowTwo(value)    → uint32_t   // next power of two >= value
+mathMax(a, b)                         // macro
+mathMin(a, b)                         // macro
+mathClamp(x, lower, upper)            // macro
+mathAbs(amt)                          // macro
+mathModFloat(x, y)       → float_t    // always non-negative modulo
+mathLerp(a, b, t)        → float_t    // linear interpolation (floats)
+```
+
+For fixed-point lerp use `fixedLerp(a, b, t)` from `util/fixed.h`.
+
+`MATH_PI` is defined as `M_PI`.
+
+---
+
+## Fixed-point (`util/fixed.h`)
+
+Q24.8 format: 24-bit integer part, 8-bit fractional part (`int32_t`). See [architecture.md](architecture.md#fixed-point-math) for the full API.
+
+Quick reference:
+```c
+FIXED(1.5f)               // compile-time literal
+fixedFromI32(3)           // runtime int → fixed
+fixedToFloat(f)           // fixed → float (only for GL/platform APIs)
+fixedMul(a, b)            // multiplication (not just addition)
+fixedDiv(a, b)            // division
+fixedLerp(a, b, t)        // lerp where t ∈ [0, FIXED_ONE]
+```
+
+---
+
+## Array (`util/array.h`)
+
+```c
+arrayReverse(array, count, size);   // in-place reverse; size = sizeof(element)
+```
+
+---
+
+## Sort (`util/sort.h`)
+
+```c
+sortQuick(array, count, size, compare);   // quicksort
+sortBubble(array, count, size, compare);  // bubble sort (small arrays)
+sort(array, count, size, compare);        // macro alias for sortQuick
+
+// Convenience uint8_t sorter:
+sortArrayU8(array, count);
+int sortArrayU8Compare(const void *a, const void *b);   // comparator
+```
+
+`sortcompare_t` matches `qsort` comparator signature: `int (*)(const void *, const void *)`.
+
+---
+
+## Reference counting (`util/ref.h`)
+
+```c
+refInit(&ref, dataPtr, onLock, onUnlock, onAllUnlocked);
+refLock(&ref);              // increments count, calls onLock
+bool_t hit_zero = refUnlock(&ref);   // decrements; calls onAllUnlocked when 0
+```
+
+Used internally by the asset entry system to track how many callers hold a reference to a loaded asset entry.
+
+---
+
+## CRC32 (`util/crypt.h`)
+
+```c
+// One-shot:
+uint32_t crc = cryptCRC32(data, size);
+
+// Streaming:
+uint32_t acc = cryptCRC32Begin();
+cryptCRC32Update(&acc, chunk1, len1);
+cryptCRC32Update(&acc, chunk2, len2);
+uint32_t final = cryptCRC32End(acc);
+```
+
+Used by the save stream to checksum save files.
+
+---
+
+## Endian (`util/endian.h`)
+
+All serialized data (save files, asset headers) is little-endian. Convert to/from host byte order:
+
+```c
+uint32_t val = endianLittleToHost32(rawU32);
+uint16_t val = endianLittleToHost16(rawU16);
+float_t  val = endianLittleToHostFloat(rawFloat);
+```
+
+`isHostLittleEndian()` returns a bool at runtime. The compile-time defines `DUSK_PLATFORM_ENDIAN_LITTLE` / `DUSK_PLATFORM_ENDIAN_BIG` are set by `cmake/targets/<target>.cmake`.