libstringstack(3) FreeBSD Library Functions Manual libstringstack(3) NAME libstringstack – Dynamically resized stacks and strings SYNOPSIS #include -I/usr/local/include -L/usr/local/lib -lstringstack DESCRIPTION LibStringStack provides dynamically resized stacks and character arrays. All library functions are reentrant if concurrent invocations are applied to different structures. USAGE The library uses structures defined in stringstack.h: STACKS union stack_val { float num; void *ptr; }; struct stack { int free, used; union stack_val *top, *values; }; The free and used elements describe the number of free and used elements in the values list. The values list contains a contiguous array of union stack_val pointers of length followed by empty slots. The top element points to the union stack_val on the top of the stack. If the stack is empty, top points to the first slot in the values list. stack_make() creates stacks with 64 free slots in the values list. Pushing more than 64 elements causes the values list to be resized to its current size plus 64 more slots. Stacks never shrink. You iterate over a stack like this: int i; union stack_val *p; for( i = 0, p = stack->values; i < stack->used; ++i, ++p ) do_something_with( p ); STRINGS struct string { int free, used; char *top, *str; }; The free and used elements describe the number of free and used characters in the str array. The str array contains a contiguous array of characters of length followed by the zero terminator, followed by empty slots. The top element points to zero terminator in the str array. If the stack is empty, the terminator will be in the first slot in the str array. string_make() creates strings with 128 free characters in the str array. Pushing more than 128 characters causes the str array to be resized to its current size plus 128 more characters. Strings never shrink. STACK_MAKE() Create a new stack with stack_make(). struct stack *stack_make(); stack_make() returns a pointer to a new stack initialized for use. If memory allocation fails, stack_make() returns NULL. STACK_FREE() Deallocate stacks with stack_free(). void stack_free( struct stack *stack ); STACK_CLEAR() Empty a stack with stack_clear(). void stack_clear( struct stack *stack ); STACK_PUSH() Push an element onto the top of a stack with stack_push(). struct stack *stack_push( struct stack *stack, union stack_val item ); stack_push() returns 0 on success, or 1 if memory allocation fails. The first argument is the stack. The second argument is the item to be pushed onto the stack. The content of the union stack_val is copied into the stack by structure assignment. STACK_POP() Pop the top element off a stack with stack_pop(). union stack_val *stack_pop( struct stack *stack ); stack_pop() returns NULL if the stack is empty. On success, stack_pop() returns a pointer to the element that was on top of the stack before the call to stack_pop(). The element will be overwritten by the next call to stack_push(). To preserve the element, assign its data to another union stack_val with structure assignment. union stack_val temp, *ptr; if (( ptr = stack_pop( stack )) != NULL ) temp = *ptr; STACK_UNSHIFT() Push an element onto the bottom of the stack with stack_unshift(). int stack_unshift( struct stack *stack, union stack_val item ); stack_unshift() returns 0 on success, or 1 if memory allocation fails. The first argument is the stack. The second argument is the item to be pushed onto the stack. The content of the union stack_val is copied into the stack by structure assignment. STACK_SHIFT() Pop the bottom element off a stack with stack_shift(). int stack_shift( struct stack *stack, union stack_val *item ); The first argument is the stack. The second argument is a pointer to a union stack_val to hold the result. stack_shift() returns 1 if the stack is empty. On success, stack_shift() returns 0. On success, the union stack_val pointed to by the second argument contains the content of the element that was on the bottom of the stack before stack_shift() was invoked. The result is copied by structure assignment. STRING_MAKE() Create a new string with string_make(). struct string *string_make( char *source ); The argument is a source character array to initialize the string. The argument can be NULL. STRING_FREE() Deallocate a string with string_free(). void string_free( struct string * ); STRING_CLEAR() Empty a string with string_clear(). void string_clear( struct string *string ); STRING_APPEND() Add a single character to the end of a string with string_append(). int string_append( struct string *string, char c ); string_append() returns 0 on success or 1 if memory allocation fails. You can append zero to a string. The first argument is the string. The second argument is the character to be appended. STRING_PREPEND() Add a single character to the front of a string with string_prepend(). int string_prepend( struct string *string, char c ); string_prepend() returns 0 on success or 1 if memory allocation fails. You can prepend 0 to a string. The first argument is the string. The second argument is the character to be prepended. STRING_ASSIGN() Assign a character array to a string with string_assign(). int string_assign( struct string *string, char *array ); string_assign() returns 0 on success or 1 if memory allocation fails. The previous content of the string is discarded. You cannot append a string containing 0. The first argument is the string. The second argument is the character array to be assigned to the string. STRING_CONCAT() Append a character array to a string with string_concat(). int string_concat( struct string *string, char *array ); string_concat() returns 0 on success or 1 if memory allocation fails. The character array is appended to the current content of the string. You cannot concat a string containing 0. The first argument is the string. The second argument is the character array. STRING_PRECAT() Prepend a character array to a string with string_concat(). int string_precat( struct string *string, char *array ); string_precat() returns 0 on success or 1 if memory allocation fails. The character array is prepended to the current content of the string. You cannot prepend a string containing 0. The first argument is the string. The second argument is the character array. STRING_MERGE() Append the content of one string to another string with string_merge(). int string_merge( struct string *a, struct string *b ); string_merge() returns 0 on success or 1 if memory allocation fails. On success, string b's content is appended to the content of string a. String b is unchanged. The first argument is the string to be altered. The second argument is the source string. If you do not want either string to be affected, use struct string *new = string_make( a->str ); string_concat( new, b->str ); STRING_UTF8_LEN() Count the length of an UTF-8 string with string_UTF8_len(). unsigned int string_UTF8_len( unsigned char * ); STRING_UTF16_LEN() Count the length of an UTF-16 string with string_UTF16_len(). unsigned int string_UTF16_len( unsigned char * ); STRING_UTF8_TO_VALUE() Convert a single UTF-8 character into an unsigned int with string_UTF8_to_value(). unsigned int string_UTF8_to_value( unsigned char * ); STRING_UTF8_TO_UTF32BE() Convert an UTF-8 string to an UTF-32BE string with string_UTF8_to_UTF32BE(). struct string *string_UTF8_to_UTF32BE( struct string * ); STRING_UTF8_TO_UTF16BE() Convert an UTF-8 string into an UTF-16BE string with string_UTF8_to_UTF16BE(). struct string *string_UTF8_to_UTF16BE( struct string * ); STRING_UTF16_TO_UTF8() Convert an UTF16 string of either endianness to an UTF-8 string with string_UTF16_to_UTF8(). struct string *string_UTF16_to_UTF8( struct string * ); STRING_UTF32BE_TO_UTF8() Convert an UTF-32BE string into an UTF-8 string with string_UTF32BE_to_UTF8(). struct string *string_UTF32BE_to_UTF8( struct string * ); AUTHORS James Bailie ⟨jimmy@mammothcheese.ca⟩ http://www.mammothcheese.ca Thu Feb 08, 2024