fwBase — Base Types & Utilities

Overview

What It Does

fwBase is the root of the fw-lib dependency tree. It provides string utilities, time functions, basic file I/O, and the error stack used by all other libraries to report failures up the call chain.

Most importantly, fwBase hosts the FLOG callback infrastructure (fwLibLog.h). Other fw-libs call FLOG_* macros to emit structured log messages; fwBase owns the callback pointer that routes those messages to the application's logging system. Because fwBase itself hosts this infrastructure, it must not use FLOG_* macros internally — doing so would cause unbounded recursion through the callback it provides.

Trace Levels

fwBase uses trace levels 1–19. See the full trace level table for all assignments across the fw-lib stack.

API Reference

Types & Macros

Utility Macros (fwMacros.h)

Macro	Description
`FW_VEC_SIZE(a)`	Get array size in items
`FW_MAX(a, b)`	Maximum of two values
`FW_MIN(a, b)`	Minimum of two values
`FW_FT(b)`	bool to `"true"`/`"false"` string
`FW_SET(b)`	bool to `"set"`/`"unset"` string

API Reference

String Functions

fwStringSplit

int fwStringSplit(char* s, char delimiter, char** sVec, int sVecLen);

Splits a string into a vector of substrings by delimiter. In-place operation — replaces delimiters with null terminators in the original buffer. Returns the number of items found.

char str[] = "one:two:three";
char* parts[10];
int count = fwStringSplit(str, ':', parts, 10);
// count=3, parts[0]="one", parts[1]="two", parts[2]="three"

fwStringReplace

char* fwStringReplace(const char* in, const char* replace, const char* with,
                      char* out, int outLen);

Replaces all occurrences of a substring. Returns a pointer to the output buffer.

fwStringArrayJoin

void fwStringArrayJoin(char* output, int outputLen, char** stringV,
                       int vecItems, const char* separator);

Joins an array of strings with a separator into a single output buffer.

fwStringArrayLookup

int fwStringArrayLookup(char** stringV, int vecItems, const char* needle);

Linear search for a string in an array. Returns the index or -1 if not found.

Other String Functions

Function	Description
`fwStringSort(char* s)`	Sorts characters within a string alphabetically (in-place)
`fwStringInList(char* commaList, char* what)`	Checks if value exists in a comma-separated string list
`fwStrEq(const char* s1, const char* s2)`	String equality — returns true if equal
`fwCharCount(char* haystack, char needle)`	Counts occurrences of a character in a string
`fwCharChecksum(void* buf, int bufLen)`	Simple checksum (sum of bytes) of a buffer
`fwFloatTrim(char* floatString, double d)`	Converts double to string, strips trailing zeros

API Reference

File & Time Functions

File Functions

Function	Description
`fwFileRead(char* base, char* relPath, char** bufP, int* bufLenP)`	Reads entire file into an allocated buffer. Returns 0 on success.
`fwFileSuffixExtract(char* fileName, int len, bool destructive)`	Extracts file extension from a filename
`fwProgName(char* argv0)`	Extracts program name from `argv[0]`, stripping directory path. No allocation needed.

Time Functions

Function	Description
`fwTimeGet(struct timespec* tP)`	Gets current time using `CLOCK_REALTIME`
`fwTimeDiff(start, end, diff, float*)`	Calculates time difference; outputs as timespec and optionally as float seconds
`fwTimeAccumulate(accumulated, part, float*)`	Adds a timespec to an accumulator; useful for measuring total elapsed time

API Reference

Error Stack

The error stack collects structured errors with file/line/function context and allows them to be flushed or reported as a batch — useful for validation routines that accumulate multiple errors before returning.

typedef struct FwErrorItem {
    const char* file;
    int         line;
    const char* function;
    int         code;
    const char* title;
    const char* detail;
} FwErrorItem;

typedef struct FwErrorStack {
    FwErrorItem* errorV;
    int          errorSize;
    int          ix;
} FwErrorStack;

Function	Description
`fwErrorInit(esP, maxItems)`	Initialize error stack with capacity
`fwErrorPush(esP, code, title, detail)`	Push an error onto the stack
`fwErrorFlushToScreen(esP)`	Print all errors to stderr
`fwErrorFree(esP)`	Free error stack memory

Design

Design Philosophy

No unnecessary allocation — functions like fwStringSplit and fwProgName avoid malloc by operating in-place or returning pointers into the input
In-place operations — string functions modify input buffers where appropriate; callers pass writable copies when the original must be preserved
C standard library conventions — NULL checks omitted in performance-critical functions; callers are responsible for valid inputs
Macro-based logging — FLOG_* macros in fwBase automatically capture file/line/function context via the preprocessor