libstringstack(8)       FreeBSD System Manager's Manual      libstringstack(8)

NAME
     libstringstack - Dynamically resized stacks and strings

SYNOPSIS
     #include <stringstack.h>
     -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
     {
        int 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
     <used> length followed by <free> 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 <used> length
     followed by the zero terminator, followed by <free> 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.

   MAKE_STACK()
     Create a new stack with make_stack().

     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 a pointer to the stack on success or NULL if memory
     allocation fails.

     The first argument is the stack.

     The second argument is the item to be pushed onto the stack.

   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;

   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.

     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.

     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.

     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.

     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.

     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 );

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                                 June 28, 2017