Skip to content

API Reference

Jump to bottom
Pablo R. edited this page Sep 29, 2025 · 2 revisions

API Reference

Error Handling Functions

strap_error_t strap_last_error(void)

Gets the last error code set by STRAP operations.

Returns:

  • The last error code that occurred

Example:

char *result = strtrim(NULL);
if (!result) {
    strap_error_t err = strap_last_error();
    fprintf(stderr, "Error: %s\n", strap_error_string(err));
}

const char *strap_error_string(strap_error_t err)

Converts an error code to a human-readable string.

Parameters:

  • err - Error code to convert

Returns:

  • Human-readable error description

Example:

strap_error_t err = strap_last_error();
printf("Error: %s\n", strap_error_string(err));

void strap_clear_error(void)

Clears the current error state.

Example:

strap_clear_error(); // Reset error state

Safe Reading Functions

char *afgets(FILE *f)

Reads a complete line from the file stream, automatically handling memory allocation.

Parameters:

  • f - File stream to read from

Returns:

  • Malloc-allocated buffer containing the line (without newline)
  • NULL on error/EOF

Notes:

  • Caller is responsible for freeing the returned buffer
  • Cross-platform compatible (uses fgets internally)

Example:

FILE *fp = fopen("example.txt", "r");
char *line = afgets(fp);
if (line) {
    printf("Line: %s\n", line);
    free(line);
}
fclose(fp);

char *afread(FILE *f, size_t *out_len)

Reads the entire contents of a file into memory.

Parameters:

  • f - File stream to read from
  • out_len - Pointer to store the length of the read data (can be NULL)

Returns:

  • Malloc-allocated buffer containing file contents
  • NULL on error

Notes:

  • Caller is responsible for freeing the returned buffer
  • File position is preserved after operation

Example:

FILE *fp = fopen("data.txt", "r");
size_t len;
char *content = afread(fp, &len);
if (content) {
    printf("File size: %zu bytes\n", len);
    printf("Content: %s\n", content);
    free(content);
}
fclose(fp);

String Manipulation Functions

char *strjoin(const char **parts, size_t nparts, const char *sep)

Joins multiple strings with a separator.

Parameters:

  • parts - Array of strings to join
  • nparts - Number of strings in the array
  • sep - Separator string (can be NULL for no separator)

Returns:

  • Malloc-allocated buffer containing the joined string
  • NULL on memory allocation failure

Example:

const char *words[] = {"Hello", "beautiful", "world"};
char *sentence = strjoin(words, 3, " ");
printf("%s\n", sentence); // "Hello beautiful world"
free(sentence);

char *strjoin_va(const char *sep, ...)

Variable argument version of strjoin.

Parameters:

  • sep - Separator string
  • ... - Variable number of string arguments, terminated by NULL

Returns:

  • Malloc-allocated buffer containing the joined string
  • NULL on memory allocation failure

Example:

char *path = strjoin_va("/", "usr", "local", "bin", NULL);
printf("%s\n", path); // "/usr/local/bin"
free(path);

bool strstartswith(const char *s, const char *prefix)

Checks if a string starts with a given prefix.

Parameters:

  • s - String to check
  • prefix - Prefix to look for

Returns:

  • true if string starts with prefix, false otherwise

Example:

if (strstartswith("hello.txt", "hello")) {
    printf("File has expected prefix\n");
}

bool strendswith(const char *s, const char *suffix)

Checks if a string ends with a given suffix.

Parameters:

  • s - String to check
  • suffix - Suffix to look for

Returns:

  • true if string ends with suffix, false otherwise

Example:

if (strendswith("document.txt", ".txt")) {
    printf("File is a text file\n");
}

char *strreplace(const char *s, const char *search, const char *replacement)

Replaces all occurrences of a substring with another string.

Parameters:

  • s - Original string
  • search - Substring to replace
  • replacement - Replacement string

Returns:

  • Malloc-allocated buffer containing the modified string
  • NULL on memory allocation failure

Example:

char *result = strreplace("Hello world", "world", "STRAP");
printf("%s\n", result); // "Hello STRAP"
free(result);

char *strtolower_locale(const char *s, const char *locale_name)

Converts a string to lowercase using locale-aware conversion.

Parameters:

  • s - String to convert
  • locale_name - Locale name (can be NULL for default locale)

Returns:

  • Malloc-allocated buffer containing the lowercase string
  • NULL on memory allocation failure

Example:

char *lower = strtolower_locale("HELLO", "en_US.UTF-8");
printf("%s\n", lower); // "hello"
free(lower);

char *strtoupper_locale(const char *s, const char *locale_name)

Converts a string to uppercase using locale-aware conversion.

Parameters:

  • s - String to convert
  • locale_name - Locale name (can be NULL for default locale)

Returns:

  • Malloc-allocated buffer containing the uppercase string
  • NULL on memory allocation failure

Example:

char *upper = strtoupper_locale("hello", "en_US.UTF-8");
printf("%s\n", upper); // "HELLO"
free(upper);

int strcoll_locale(const char *a, const char *b, const char *locale_name)

Compares two strings using locale-aware collation.

Parameters:

  • a, b - Strings to compare
  • locale_name - Locale name (can be NULL for default locale)

Returns:

  • Negative value if a < b, 0 if equal, positive value if a > b

Example:

int result = strcoll_locale("café", "cafe", "fr_FR.UTF-8");
if (result > 0) {
    printf("café comes after cafe in French collation\n");
}

int strcasecmp_locale(const char *a, const char *b, const char *locale_name)

Case-insensitive string comparison using locale-aware collation.

Parameters:

  • a, b - Strings to compare
  • locale_name - Locale name (can be NULL for default locale)

Returns:

  • Negative value if a < b, 0 if equal, positive value if a > b

Example:

int result = strcasecmp_locale("Hello", "HELLO", "en_US.UTF-8");
if (result == 0) {
    printf("Strings are equal ignoring case\n");
}

char *strtrim(const char *s)

Trims whitespace from both ends of a string.

Parameters:

  • s - Input string

Returns:

  • Malloc-allocated buffer containing the trimmed string
  • NULL if input is NULL or memory allocation fails

Notes:

  • Trims spaces, tabs, newlines, and carriage returns
  • Original string is not modified

Example:

char *trimmed = strtrim("  Hello World  \n");
printf("'%s'\n", trimmed); // "Hello World"
free(trimmed);

void strtrim_inplace(char *s)

Trims whitespace from both ends of a string in-place.

Parameters:

  • s - String to modify (must be mutable)

Notes:

  • Modifies the input string directly
  • No memory allocation/deallocation
  • Safe to call with NULL (no-op)

Example:

char buffer[] = "  Hello World  \n";
strtrim_inplace(buffer);
printf("'%s'\n", buffer); // "Hello World"

Arena Allocator Functions

strap_arena_t *strap_arena_create(size_t block_size)

Creates a new arena allocator.

Parameters:

  • block_size - Initial block size for allocations

Returns:

  • Pointer to new arena allocator
  • NULL on memory allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
if (!arena) {
    fprintf(stderr, "Failed to create arena\n");
    return 1;
}
// Use arena...
strap_arena_destroy(arena);

void strap_arena_destroy(strap_arena_t *arena)

Destroys an arena allocator and frees all memory.

Parameters:

  • arena - Arena to destroy

Example:

strap_arena_t *arena = strap_arena_create(1024);
// ... use arena
strap_arena_destroy(arena);

void strap_arena_clear(strap_arena_t *arena)

Clears an arena allocator, freeing all allocated memory but keeping the arena itself.

Parameters:

  • arena - Arena to clear

Example:

strap_arena_t *arena = strap_arena_create(1024);
// ... allocate some memory
strap_arena_clear(arena); // Free all allocations, keep arena

void *strap_arena_alloc(strap_arena_t *arena, size_t size)

Allocates memory from an arena.

Parameters:

  • arena - Arena to allocate from
  • size - Size of allocation in bytes

Returns:

  • Pointer to allocated memory
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
int *numbers = strap_arena_alloc(arena, sizeof(int) * 10);
// Use numbers...
strap_arena_destroy(arena);

char *strap_arena_strdup(strap_arena_t *arena, const char *s)

Duplicates a string using arena allocation.

Parameters:

  • arena - Arena to allocate from
  • s - String to duplicate

Returns:

  • Arena-allocated duplicate of the string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *copy = strap_arena_strdup(arena, "Hello World");
printf("%s\n", copy);
strap_arena_destroy(arena);

char *strap_arena_strndup(strap_arena_t *arena, const char *s, size_t n)

Duplicates up to n characters of a string using arena allocation.

Parameters:

  • arena - Arena to allocate from
  • s - String to duplicate
  • n - Maximum number of characters to copy

Returns:

  • Arena-allocated duplicate of the string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *copy = strap_arena_strndup(arena, "Hello World", 5);
printf("%s\n", copy); // "Hello"
strap_arena_destroy(arena);

char *strjoin_arena(strap_arena_t *arena, const char **parts, size_t nparts, const char *sep)

Joins multiple strings with a separator using arena allocation.

Parameters:

  • arena - Arena to allocate from
  • parts - Array of strings to join
  • nparts - Number of strings in the array
  • sep - Separator string

Returns:

  • Arena-allocated buffer containing the joined string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
const char *words[] = {"Hello", "world"};
char *result = strjoin_arena(arena, words, 2, " ");
printf("%s\n", result); // "Hello world"
strap_arena_destroy(arena);

char *strreplace_arena(strap_arena_t *arena, const char *s, const char *search, const char *replacement)

Replaces all occurrences of a substring using arena allocation.

Parameters:

  • arena - Arena to allocate from
  • s - Original string
  • search - Substring to replace
  • replacement - Replacement string

Returns:

  • Arena-allocated buffer containing the modified string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *result = strreplace_arena(arena, "Hello world", "world", "STRAP");
printf("%s\n", result); // "Hello STRAP"
strap_arena_destroy(arena);

char *strtolower_locale_arena(strap_arena_t *arena, const char *s, const char *locale_name)

Converts a string to lowercase using arena allocation and locale-aware conversion.

Parameters:

  • arena - Arena to allocate from
  • s - String to convert
  • locale_name - Locale name

Returns:

  • Arena-allocated buffer containing the lowercase string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *lower = strtolower_locale_arena(arena, "HELLO", "en_US.UTF-8");
printf("%s\n", lower); // "hello"
strap_arena_destroy(arena);

char *strtoupper_locale_arena(strap_arena_t *arena, const char *s, const char *locale_name)

Converts a string to uppercase using arena allocation and locale-aware conversion.

Parameters:

  • arena - Arena to allocate from
  • s - String to convert
  • locale_name - Locale name

Returns:

  • Arena-allocated buffer containing the uppercase string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *upper = strtoupper_locale_arena(arena, "hello", "en_US.UTF-8");
printf("%s\n", upper); // "HELLO"
strap_arena_destroy(arena);

char *strtrim_arena(strap_arena_t *arena, const char *s)

Trims whitespace from both ends of a string using arena allocation.

Parameters:

  • arena - Arena to allocate from
  • s - Input string

Returns:

  • Arena-allocated buffer containing the trimmed string
  • NULL on allocation failure

Example:

strap_arena_t *arena = strap_arena_create(1024);
char *trimmed = strtrim_arena(arena, "  Hello World  \n");
printf("'%s'\n", trimmed); // "Hello World"
strap_arena_destroy(arena);

Time Utility Functions

struct timeval timeval_add(struct timeval a, struct timeval b)

Adds two struct timeval values.

Parameters:

  • a, b - Time values to add

Returns:

  • Result of addition with proper carry handling

Example:

struct timeval t1 = {1, 500000}; // 1.5 seconds
struct timeval t2 = {2, 600000}; // 2.6 seconds
struct timeval sum = timeval_add(t1, t2); // 4.1 seconds

struct timeval timeval_sub(struct timeval a, struct timeval b)

Subtracts two struct timeval values.

Parameters:

  • a, b - Time values (a - b)

Returns:

  • Result of subtraction with proper borrow handling

Example:

struct timeval t1 = {5, 200000}; // 5.2 seconds
struct timeval t2 = {2, 100000}; // 2.1 seconds
struct timeval diff = timeval_sub(t1, t2); // 3.1 seconds

double timeval_to_seconds(struct timeval t)

Converts a struct timeval to seconds as a double.

Parameters:

  • t - Time value to convert

Returns:

  • Time in seconds with microsecond precision

Example:

struct timeval t = {3, 500000}; // 3.5 seconds
double seconds = timeval_to_seconds(t);
printf("%.6f seconds\n", seconds); // 3.500000 seconds

struct timeval timeval_add_minutes(struct timeval t, int minutes)

Adds minutes to a struct timeval.

Parameters:

  • t - Base time value
  • minutes - Minutes to add (can be negative)

Returns:

  • Time value with minutes added

Example:

struct timeval t = {1000, 0}; // 1000 seconds
struct timeval future = timeval_add_minutes(t, 5); // 1300 seconds

int strap_time_offset_to_string(int offset_minutes, char *buf, size_t bufsize)

Converts a timezone offset in minutes to ISO 8601 string format.

Parameters:

  • offset_minutes - Offset from UTC in minutes
  • buf - Buffer to write the result to
  • bufsize - Size of the buffer

Returns:

  • 0 on success, -1 on buffer too small

Example:

char tz_str[16];
strap_time_offset_to_string(60, tz_str, sizeof(tz_str));
printf("Timezone: %s\n", tz_str); // "+01:00"

int strap_time_parse_tz_offset(const char *str, int *offset_minutes)

Parses an ISO 8601 timezone offset string.

Parameters:

  • str - Timezone offset string (e.g., "+01:00", "Z")
  • offset_minutes - Pointer to store parsed offset in minutes

Returns:

  • 0 on success, -1 on parse error

Example:

int offset;
if (strap_time_parse_tz_offset("+05:30", &offset) == 0) {
    printf("Offset: %d minutes\n", offset); // 330
}

int strap_time_format_iso8601(struct timeval t, int offset_minutes, char *buf, size_t bufsize)

Formats a struct timeval as ISO 8601 string with timezone.

Parameters:

  • t - Time value to format
  • offset_minutes - Timezone offset in minutes
  • buf - Buffer to write the result to
  • bufsize - Size of the buffer

Returns:

  • 0 on success, -1 on buffer too small

Example:

struct timeval t = {1609459200, 0}; // 2021-01-01 00:00:00 UTC
char iso_str[32];
strap_time_format_iso8601(t, 0, iso_str, sizeof(iso_str));
printf("ISO 8601: %s\n", iso_str); // "2021-01-01T00:00:00Z"

int strap_time_parse_iso8601(const char *str, struct timeval *out, int *offset_minutes)

Parses an ISO 8601 datetime string.

Parameters:

  • str - ISO 8601 string to parse
  • out - Pointer to store parsed time value
  • offset_minutes - Pointer to store timezone offset (can be NULL)

Returns:

  • 0 on success, -1 on parse error

Example:

struct timeval t;
int offset;
if (strap_time_parse_iso8601("2021-01-01T12:30:45+05:30", &t, &offset) == 0) {
    printf("Parsed time with offset %d minutes\n", offset);
}

STRAP Wiki

Getting Started

Reference

Community

Links

Clone this wiki locally