C Utilities

Types, functions and data structures in C.

Assertions

Various utilities for dynamic and static assertions.

Header file: sneaker/libc/assert.h

ASSERT(expr)

Asserts that expr evaluates to a truthy value during runtime. Aborts the program if the assertion fails, along with print out the line number and file name of where the assertion failed.

ASSERT_STREQ(str1, str2)

Asserts that both specified strings str1 and str2 are equal. Aborts the program if the assertion fails, along with print out the line number and file name of where the assertion failed.

STATIC_ASSERT(cond)

Asserts that the specified expression cond evaluates to a truthy value during compilation. Compilation fails if the assertion fails.

Array

Array abstraction that can dynamically increase and shrink capacity.

Header file: sneaker/libc/vector.h

vector_t

vector_t vector_create()

Creates an instance of vector_t using dynamically allocated memory.

void vector_free(vector_t*)

Frees memory from the pointer of an instance of vector_t specified.

int vector_append(vector_t, void*)

Appends an element to the end of a vector_t instance specified as the first argument that holds a pointer which points to the value specified in the second argument. Returns 1 if successful, 0 otherwise.

void* vector_get(vector_t, int)

Retrieves the element pointer from a specified vector_t instance as the first argument by the zero-based index from the second argument. If the index given is out of bound, then the code exits, so it’s better to use vector_size() to make sure the index is within the bound of the vector.

void* vector_remove(vector_t, int)

Removes an element from the specified vector_t instance at the index in the second argument. If the index is within the bound of the vector, the element is removed and the pointer held in that element is returned. If the index is out of bound, then the code exits, so it’s better to use vector_size() to make sure the index is within the bound of the vector.

void* vector_set(vector_t, int, void*)

Sets the pointer held of a particular element from the specified vector_t instance. The new pointer specified in the third argument will replace the existing one in the encapsulating element, and the old pointer will be returned. Likewise, if the index in the second argument is out of bound, then the code will exit.

int vector_size(vector_t)

Gets the number of elements in the instance of vector_t provided.

const void** vector_content(vector_t)

Retrieves a list of the element pointers contained in the instance of vector_t specified.

Bitmap

Two-dimensional bitmap abstraction.

Header file: sneaker/libc/bitmap.h

bitmap_t

bitmap_t bitmap_create(size_t, size_t)

Creates an instance of bitmap_t using dynamically allocated memory by specifying the width and height of the bitmap, which are the number of bits in each respective dimension.

void bitmap_free(bitmap_t *)

Frees memory from the pointer of an instance of bitmap_t specified.

size_t bitmap_width(bitmap_t)

Gets the width of the bitmap_t instance specified.

size_t bitmap_height(bitmap_t)

Gets the height of the bitmap_t instance specified.

int bitmap_clear_bit(bitmap_t, size_t, size_t)

Clears a particular bit to 0 in the bitmap_t instance specified. The second and third arguments respectively specify the row and column of the bit to clear, both are zero-based indices. Returns 1 if successful, 0 otherwise.

If either the row or column specified are out of bound, the function returns 0.

int bitmap_is_set(bitmap_t, size_t, size_t)

Returns a value indicating whether a particular bit in the bitmap_t specified is set to 1. The second and third arguments respectively specify the row and column of the bit, both are zero-based indices. Returns 1 if the bit is set, 0 otherwise.

If either the row or column specified are out of bound, the function returns 0.

void bitmap_clear(bitmap_t)

Sets every bit in the bitmap_t specified to 0.

C-String Types

Short-hand notations for C-String types.

Header file: sneaker/libc/cstr.h

c_str

typedef of char*
cc_str

typedef of const char*

Standard Library Functions

Standard functions in C that might not be available in some compilers.

Header file: sneaker/libc/cutils.h

char* itoa(int, char*, int)

Integer to ASCII string conversion.

Converts an integer value specified as the first argument to a null-terminated string specified as the second argument. The base of the integer can be optionally specified as the third argument, which defaults to 10 if not specified. Returns the converted ASCII string.

If base is 10 and value is negative, the resulting string is preceded with a minus sign (-). With any other bases, value is always considered unsigned.

char* atoi(const char*)

ASCII string to integer conversion.

Converts an ASCII string specified as the first argument to an integer number.

The function first discards as many whitespace characters as necessary until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many numerical digits as possible, and interprets them as a numerical value.

Dictionary

A dictionary implementation with C-string typed keys, based on the hashmap_t implementation.

Header file: sneaker/libc/dict.h

dict_t

dict_t dict_create()

Creates an instance of dict_t using dynamically allocated memory.

size_t dict_size(dict_t)

Gets the number of key-value pairs in the dict_t instance specified.

void dict_free(dict_t*)

Frees memory from the pointer of an instance of dict_t specified.

void* dict_put(dict_t, const char*, void*)

Insert a key-value pair into the dict_t instance specified as the first argument. The second argument is the key and the third argument is a pointer of the value to be stored. Returns the pointer in the pair inserted. If the key already exists, then the existing value is replaced.

void* dict_get(dict_t, const char*)

Retrieves the value associated with a key specified as the second argument from the dict_t instance specified as the first argument. Returns the pointer of the value associated with the key if the key exists, NULL otherwise.

Hashing

Hashing algorithms.

Header file: sneaker/libc/hash.h

unsigned long int linear_horners_rule_str_hash(const char*)

Calculates the hash value of the specified string using a linear version of Horner’s Rule.

unsigned long int hash32shift(unsigned int)

Calculates the hash of a 32-bit unsigned integer.

unsigned long int hash64shift(unsigned long)

Calculates the hash of a 64-bit unsigned integer.

unsigned long int hash_str_jenkins_one_at_a_time(const char*)

Calculates the hash value of the specified string using the “Jenkins’s one-at-a-time” algorithm.

unsigned long int hash_robert_jenkin(unsigned int)

Calculates the hash value of the specified string using the “Robert Jenkin” algorithm.

Hash Map

A hash map implementation that offers near constant-time lookups and inserts.

Header file: sneaker/libc/hashmap.h

hashmap_t

HashFunc

Hash function used to hash keys in hashmap_t, defined as unsigned long int(*HashFunc)(void*).

KeyCmpFunc

Key comparison function used to compare keys in the hash map, defined as int(*KeyCmpFunc)(void*, void*).

hashmap_t hashmap_create(size_t, HashFunc, KeyCmpFunc)

Creates an instance of hashmap_t using dynamically allocated memory, and by specifying the initial capacity as the first argument, as well as the hashing and key comparison functions as the second and third arguments.

size_t hashmap_size(hashmap_t)

Gets the number of elements in the specified hashmap_t instance.

void hashmap_lock(hashmap_t)

Locks the specified hashmap_t instance so that updates from other threads are blocks until hashmap_unlock is called on the instance.

void hashmap_unlock(hashmap_t)

Unlocks the specified hashmap_t instance following a previous call of hashmap_lock so that updates from other threads are unblocked.

void hashmap_free(hashmap_t*)

Frees memory from the pointer of an instance of hashmap_t specified.

void* hashmap_put(hashmap_t, void*, void*)

Inserts a key-value pair into the hashmap_t instance as the first argument. If the key already exists, its associated value will be updated. Returns the value inserted if successful, NULL otherwise.

void* hashmap_get(hashmap_t, void*)

Retrieves the value associated with the key specified as the second argument from the hashmap_t instance specified as the first argument. Returns the value if its associated key is in the instance, NULL otherwise.

int hashmap_contains_key(hashmap_t, void*)

Returns a value indicating if the key specified as the second argument exists in the hashmap_t instance specified as the first argument. Returns 1 if the key is in the instance, 0 otherwise.

void* hashmap_remove(hashmap_t, void*)

Removes the key-value pair from the hashmap_t instance specified as the first argument using the key as the second argument. Returns the value associated with the key if found, NULL otherwise.

void* hashmap_lookup(hashmap_t, void*, void*)

Looks up a particular key-value pair from the hashmap_t instance as the first argument. The lookup function is the second argument that has the signature int(*lookup)(void *key, void *value, void* arg), which takes a key, its associated value and an optional argument which is specified as the third argument. The lookup function returns 1 for a key-value pair considered as found, at which the function stops the searching and returns the value found. If no key-value is found, returns NULL.

void hashmap_iterate(hashmap_t, void*, int)

Iterates through all key-value pairs in the hashmap_t instance as the first argument. The second argument specifies a function of signature int(*callback)(void *key, void *value) that receives every key-value pair iterated. The third argument specifies a value that indicates whether the iteration should continue when the callback function returns a non-truthy value.

size_t hashmap_bucketcount(hashmap_t)

Returns the number of buckets in the hashmap_t instance specified as the first argument.

size_t hashmap_capacity(hashmap_t)

Returns the capacity of the hashmap_t instance specified as the first argument.

int hashmap_equal(hashmap_t, hashmap_t)

Determines equality between the two instances of hashmap_t specified. The two instances would only be considered equal if they have exactly the same keys and all associated values of the same keys must be identical as well. Returns 1 if they are considered equal, 0 otherwise.

Math

General functions for mathematical computations.

Header file: sneaker/libc/math.h

unsigned int nearest_exp2_ceil(unsigned int)

Computes the least largest exponent of base 2 that is closest to the input value.

unsigned int nearest_exp2_floor(unsigned int)

Computes the most largest exponent of base 2 that is closest to the input value.

Queue

A FIFO storage container.

Header file: sneaker/libc/queue.h

queue_t

queue_t queue_create()

Creates an instance of queue_t using dynamically allocated memory.

size_t queue_size(queue_t)

Gets the number of elements in the queue_t instance specified.

void* queue_front(queue_t)

Gets the element pointer at the front of the queue_t instance specified. If the queue is empty, NULL is returned.

void* queue_back(queue_t)

Gets the element pointer at the back of the queue_t instance specified. If the queue is empty, NULL is returned.

int queue_push(queue_t, void*, size_t)

Pushes an element pointer to the back of the queue_t instance specified as the first argument. The second argument is a pointer that points to the value to be pushed onto the queue, and the third argument is the size of the value to be pushed, in number of bytes. Returns -1 if the push failed, 1 if successful.

void* queue_pop(queue_t)

Pops the element pointer at the front of the queue_t instance specified and returns it. If the queue is empty, NULL is returned.

void queue_free(queue_t *)

Frees memory from the pointer of an instance of queue_t specified.

Stack

A FILO storage container.

Header file: sneaker/libc/stack.h

sstack_t

sstack_t stack_create()

Creates an instance of sstack_t using dynamically allocated memory.

size_t stack_size(sstack_t)

Returns the number of elements in the sstack_t instance specified.

void* sstack_top(sstack_t)

Gets the element pointer at the top of the sstack_t instance provided. Returns NULL if the stack is empty.

int stack_push(sstack_t, void*, size_t)

Pushes an element pointer to the top of the sstack_t instance specified as the first argument. The second argument is a pointer that points to the value to be pushed onto the stack, and the third argument is the size of the value to be pushed, in number of bytes. Returns -1 if the push failed, 1 if successful.

void* stack_pop(sstack_t)

Pops the element pointer at the top of the sstack_t instance specified and returns it. If the stack is empty, NULL is returned.

void stack_free(stack*)

Frees memory from the pointer of an instance of sstack_t specified.

String Buffer

A C-string buffer abstraction that can dynamically change capacity.

Header file: sneaker/libc/strbuf.h

strbuf_t

strbuf_t strbuf_t_create()

Creates an instance of strbuf_t using dynamically allocated memory.

void strbuf_free(strbuf_t*)

Frees memory from the pointer of an instance of strbuf_t specified.

void strbuf_empty(strbuf_t)

Empties the strbuf_t instance specified as the argument and reduces its capacity to 0.

size_t strbuf_len(strbuf_t)

Gets the length of the string currently held in the strbuf_t instance specified as the argument.

const char* strbuf_cstr(strbuf_t)

Gets the C-string held in the strbuf_t instance specified as the argument.

size_t strbuf_capacity(strbuf_t)

Gets the capacity of the strbuf_t instance specified as the argument.

int strbuf_append(strbuf_t, const char*)

Appends a C-string into the strbuf_t instance specified as the first argument. The second argument is the C-string to be appended. Returns 1 if the append is successful, 0 otherwise.

String Manipulation

String manipulation functions.

Header file: sneaker/libc/strutils.h

char* strtoupper(char *)

Converts the C-string specified as the argument to its uppercase form. Returns the converted string.

char* strtolower(char *)

Converts the C-string specified as the argument to its lowercase form. Returns the converted string.

char* strtrim(char *)

Trims off empty spaces at the front and end of the string specified. Returns the trimmed string.

char* strcpy_hard(char*, const char*)

Copies the source string specified as the second argument to the destination string specified as the first argument. If the length of the source string is greater than the length of the destination string, then the destination string is freed and re-allocated to have the same length as the source string. Returns the destination string.

char* strncpy_safe(char*, const char*, size_t)

Copies the source string specified as the second argument to the destination string specified as the first argument. The number of characters copied is the minimum between the length of the destination string and the size specified as the third argument. Returns the destination string.

size_t strlcpy2(char*, const char*, size_t)

Copies the source string specified as the second argument to the destination string specified as the first argument. The number of characters copied is at most the number specified as the third argument minus 1. Returns the number of characters tried to be copied, which is the size of the source string.

General Utilities

General utility functions.

Header file: sneaker/libc/utils.h

void set_nth_bit(int*, char)

Set a specific bit of a given number to 1. The first argument specifies a pointer to the number to be set, and the second argument is the `n`th bit to set from the LSB.

void clear_nth_bit(int*, char)

Clears a specific bit of a given number to 0. The first argument specifies a pointer to the number to be cleared, and the second argument is the `n`th bit to clear from the LSB.

int is_bit_set(int, char)

Checks if a specific bit of a given number is set to 1. The first argument specifies a pointer to the number to be checked, and the second argument is the n`th bit to check from the LSB. Returns `1 if the bit is set to 1, 0 otherwise.

void set_nth_bit_uint32(uint32_t*, char)

32-bit version of set_nth_bit.

void clear_nth_bit_uint32(uint32_t*, char)

32-bit version of clear_nth_bit.

int is_bit_set_uint32(uint32_t, char)

32-bit version of is_bit_set.

void set_nth_bit_uint8(uint8_t *val, char bit)

8-bit version of set_nth_bit.

void clear_nth_bit_uint8(uint8_t *val, char bit)

8-bit version of clear_nth_bit.

int is_bit_set_uint8(uint8_t val, char bit)

8-bit version of is_bit_set.

int rand_top(int)

Returns an pseudo-random integer that’s in the range between 1 and the number specified as the argument, inclusively.

int rand_range(int, int)

Returns an pseudo-random integer that’s in the range between two integers specified as the two arguments, inclusively.

double randf_top(double)

Returns an pseudo-random double-precision floating number that’s in the range between 1 and the number specified as the argument, inclusively.

double randf_range(double, double)

Returns an pseudo-random double-precision floating number that’s in the range between two double-precision floating numbers specified as the two arguments, inclusively.

char* generate_text(size_t=0, size_t=0)

Generates a random string of an optional length specified as the first argument, up to the optional maximum length specified as the second argument.

If both the length and max length are non-zero, the generated text will have a length between the two numbers.

If only the length is non-zero, the generated text will have exactly the specified length.

If only the max length is non-zero, the generated text will have a length between 1 and the max length, inclusively.

If both the length and max length are zero, NULL is returned.

char* generate_loremipsum()

Generates a string of Lorem Ipsum of arbitrary length.

Universally Unique Identifier

A 128-bits implementation of UUID.

Header file: sneaker/libc/uuid.h

uuid128_t

uuid128_t uuid_create()

Creates an instance of uuid128_t using dynamically allocated memory.

int uuid_compare(const uuid128_t, const uuid128_t)

Evaluates equality between two instances of uuid128_t. Returns 1 if the first argument is considered greater than the second, 0 if they are equivalent, and -1 if the first is less than the second.

__uint128_t uuid_to_hash(const uuid128_t)

Hashes the uuid128_t instance provided as the arugment to an 128-bit unsigned integer.

__uint128_t uuid_create_and_hash()

Creates an instance of uuid128_t and returns its equivalent hash.