5.0 KiB
Utilities
Source: src/dusk/util/
String (util/string.h)
Always use these instead of stdlib equivalents (strcmp, strcpy, sprintf, etc.).
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.
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)
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 for the full API.
Quick reference:
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)
arrayReverse(array, count, size); // in-place reverse; size = sizeof(element)
Sort (util/sort.h)
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)
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)
// 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:
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.