BOOLEAN_STR

Definition:

Usage:

Returns the string represenation of the value or expression in b.

CORE

Definition:

Usage:

Enforces a SIGSEGV by writing to invalid memory.

FALSE

Definition:

Usage:

Value 0 for FALSE.

LOG

Definition:

Usage:

Write any logging output to trace.

This function is newer than the previous ones, and allows for a printf-like format string with variable amount of parameters.

format is a printf()-like format-string. ... parameters in the way they occur in the format-string.

MAKE_BOOLEAN

Definition:

Usage:

Turns the value or expression b into a pboolean value TRUE or FALSE.

MISSINGCASE

Definition:

Usage:

Prints "missing case engaged" into stderr, to indicate switch-case constructs running into default-branch because any other branch is not engaged.

MSG

Definition:

Usage:

Write a message to trace.

message is your message!

OUTOFMEM

Definition:

Usage:

Prints "ran out of memory" into stderr and exits with status 1.

PARMS

Definition:

Usage:

Write parameter content to trace.

The PARMS-macro is used to write parameter names and values to the program trace. PARMS() should - by definition - only be used right behind PROC(). If the logging of variable values is wanted during a function execution to trace, the VARS()-macro shall be used.

param_name is the name of the parameter format is a printf-styled format placeholder. parameter is the parameter itself.

PROC

Definition:

Usage:

Write function entry to trace.

The PROC-macro introduces a new function level, if compiled with trace.

The PROC-macro must be put behind the last local variable declaration and the first code line, else it won't compile. A PROC-macro must exists within a function to allow for other trace-macro usages. If PROC() is used within a function, the macros RETURN() or VOIDRET, according to the function return value, must be used. If PROC is used without RETURN, the trace output will output a wrong call level depth.

The parameter func_name is a static string for the function name.

RETURN

Definition:

Usage:

Write function return to trace. RETURN() can only be used if PROC() is used at the beginning of the function. For void-functions, use the macro VOIDRET.

return_value is return-value of the function.

TODO

Definition:

Usage:

Prints "TODO alert!" into stderr, to inform about incomplete branches.

TRUE

Definition:

Usage:

Value 1 for TRUE.

VARS

Definition:

Usage:

Write variable content to trace.

The VARS-macro is used to write variable names and values to the program trace. For parameters taken to functions, the PARMS()-macro shall be used.

var_name is the name of the variable format is a printf-styled format placeholder. variable is the parameter itself.

VOIDRET

Definition:

Usage:

Write void function return to trace.

VOIDRET can only be used if PROC() is used at the beginning of the function. For typed functions, use the macro RETURN().

WRONGPARAM

Definition:

Usage:

Prints "function called with wrong or incomplete parameters" into stderr, to indicate invalid function calls.

parray_for

Definition:

Usage:

Macro that expands into a for-loop iterating a parray-object array using and pointer variable ptr as walker.

This macro expands into a for-loop in the format

for( ptr = parray_first( array ); ptr; ptr = parray_next( array, ptr ) )

where ptr is a walker variable of the same type size of the array's size for each element.

Example:

usertype* 	t;
parray		a;

parray_init( &a, sizeof( usertype ), 0 );

parray_for( a, t )
{
	/* Do something with t *}

plist_for

Definition:

Usage:

Macro that expands into a for-loop iterating a plist-object l using the element variable e as walker.

This macro expands into a for-loop of the format

for( e = plist_first( l ); e; e = plist_next( e ) )

where e is a walker variable for each element.

Example:

plist*		my_list;
plistel*	e;

plist_for( my_list, e )
{
	/* Access current element data part *	ptr = (cast*)plist_access( e );
	...
}

parray_concat

Definition:

Usage:

Concats the elements of array src to the elements of array dest.

The function will not run if both arrays have different element size settings.

The function returns the number of elements added to dest.

parray_count

Definition:

Usage:

Returns the number of elements in a array.

parray_create

Definition:

Usage:

Create a new parray as an object with an element allocation size size, a reallocation-chunk-size of chunk.

The returned memory must be released with parray_free().

parray_diff

Definition:

Usage:

Tests the contents (data parts) of the array left and the array right for equal elements.

The function returns a value < 0 if left is lower right, a value > 0 if left is greater right and a value == 0 if left is equal to right.

parray_erase

Definition:

Usage:

Erase a dynamic array.

The array must not be reinitialized after destruction, using parray_init().

array is the pointer to the array to be erased.

parray_first

Definition:

Usage:

Access first element of the array.

Returns the address of the accessed item, and NULL if nothing is in the array.

parray_free

Definition:

Usage:

Releases all the memory array uses and destroys the array object.

The function always returns (parray*)NULL.

parray_get

Definition:

Usage:

Access an element from the array by its offset position from the left.

array is the pointer to array where to access the element from. offset is the offset of the element to be accessed from the array's base address.

Returns the address of the accessed item, and NULL if the item could not be accessed (e.g. if the array is empty or offset is beyond the top of array).

Use parray_rget() for access items from the end.

parray_init

Definition:

Usage:

Performs an array initialization.

array is the pointer to the array to be initialized.

size defines the size of one array element, in bytes. This should be evaluated using the sizeof()-macro.

chunk defines the chunk size, when an array-(re)allocation will be performed. If, e.g. this is set to 128, then, if the 128th item is created within the array, a realloction is done. Once allocated memory remains until the array is freed again. The array's elements may change their heap address when a chunk reallocation is required.

parray_insert

Definition:

Usage:

Insert item item at offset into array array. Items right to offset will move up.

Gap space between the offset is filled with zero elements; Handle with care!

parray_iter

Definition:

Usage:

Iterates over array.

Iterates over all items of array and calls the function callback on every item.

parray_last

Definition:

Usage:

Access last element of the array.

Returns the address of the accessed item, and NULL if nothing is in the array.

parray_malloc

Definition:

Usage:

Pushes and "allocates" an empty element on the array.

This function is just a shortcut to `parray_push( array, NULL )`, and the memory of the pushed element is initialized to zero.

parray_next

Definition:

Usage:

Access next element from ptr in array.

Returns the address of the next element, and NULL if the access gets out of bounds.

parray_offset

Definition:

Usage:

Return offset of element ptr in array array.

Returns the offset of ptr in array. The function returns the size of the array (which is an invalid offset) if ptr is not part of array.

To check if a pointer belongs to an array, call parray_partof().

parray_partof

Definition:

Usage:

Returns TRUE, if ptr is an element of array array.

parray_pop

Definition:

Usage:

Removes an element from the end of an array.

The function returns the pointer of the popped item. Because dynamic arrays only grow and no memory is freed, the returned data pointer is still valid, and will only be overridden with the next push operation.

array is the pointer to array where to pop an item off.

The function returns the address of the popped item, and NULL if the item could not be popped (e.g. array is empty).

parray_prev

Definition:

Usage:

Access previous element from ptr in array.

Returns the address of the previous element, and NULL if the access gets out of bounds.

parray_push

Definition:

Usage:

Appends an element to the end of the array.

The element's memory is copied during the push. The item must be of the same memory size as used at array initialization.

array is the pointer to array where to push an item on.

item is the pointer to the memory of the item that should be pushed onto the array. The caller should cast his type into void, or wrap the push-operation with a macro. It can be left NULL, so no memory will be copied.

The function returns the address of the newly pushed item, and NULL if the item could not be pushed.

parray_put

Definition:

Usage:

Put an element item at position offset of array array.

array is the pointer to array where to put the element to. offset is the offset of the element to be set. item is a pointer to the memory that will be copied into the position at offset. If this is NULL, the position at offset will be set to zero.

Returns the address of the item in the array, or NULL if the desired offset is out of the array bounds.

parray_remove

Definition:

Usage:

Remove item on offset from array array.

The removed item will be copied into item, if item is not NULL. The function returns the memory of the removed item (it will contain the moved up data part or invalid memory, if on the end).

parray_reserve

Definition:

Usage:

Reserves memory for n items in array.

This function is only used to assume that no memory reallocation is done when the next n items are inserted/malloced.

parray_rget

Definition:

Usage:

Access an element from the array by its offset position from the right.

array is the pointer to array where to access the element from. offset is the offset of the element to be accessed from the array's base address.

Returns the address of the accessed item, and NULL if the item could not be accessed (e.g. if the array is empty or offset is beyond the bottom of the array).

Use parray_get() to access items from the begin.

parray_riter

Definition:

Usage:

Iterates backwards over array.

Backwardly iterates over all items of array and calls the function callback on every item.

parray_rmalloc

Definition:

Usage:

Unshifts and "allocates" an empty element on the array.

This function is just a shortcut to `parray_unshift( array, NULL )`, and the memory of the unshifted element is initialized to zero.

parray_rput

Definition:

Usage:

Put an element item at position offset from the right of array array.

array is the pointer to array where to put the element to. offset is the offset of the element to be set. item is a pointer to the memory that will be copied into the position at offset. If this is NULL, the position at offset will be set to zero.

Returns the address of the item in the array, or NULL if the desired offset is out of the array bounds.

parray_set_comparefn

Definition:

Usage:

Sets array compare function.

If no compare function is set or NULL is provided, memcmp() will be used as default fallback.

parray_set_sortfn

Definition:

Usage:

Sets array sort function.

If no sort function is given, the compare function set by parray_set_comparefn() is used. If even unset, memcmp() will be used.

parray_shift

Definition:

Usage:

Removes an element from the begin of an array.

The function returns the pointer of the shifted item. Because dynamic arrays only grow and no memory is freed, the returned data pointer is still valid, and will only be overridden with the next unshift operation.

array is the pointer to array where to pop an item off.

The function returns the address of the shifted item, and NULL if the item could not be popped (e.g. array is empty).

parray_sort

Definition:

Usage:

Sorts list according to the sort-function that was set for the list.

To sort only parts of a list, use plist_subsort().

The sort-function can be modified by using plist_set_sortfn().

The default sort function sorts the list by content using the memcmp() standard function.

parray_subsort

Definition:

Usage:

Sorts array between the elements from and to according to the sort-function that was set for the array.

To sort the entire array, use parray_sort().

The sort-function can be modified by using parray_set_sortfn().

The default sort function sorts the list by content using the memcmp() standard function.

parray_swap

Definition:

Usage:

Swap two elements of an array.

parray_union

Definition:

Usage:

Unions elements from array from into array all.

An element is only added to all, if there exists no equal element with the same size and content.

The function will not run if both arrays have different element size settings.

The function returns the number of elements added to from.

parray_unshift

Definition:

Usage:

Appends an element to the begin of the array.

The elements memory is copied during the unshift. The item must be of the same memory size as used at array initialization.

array is the pointer to array where to push an item to the beginning.

item is the pointer to the memory of the item that should be pushed onto the array. The caller should cast his type into void, or wrap the push-operation with a macro. It can be left NULL, so no memory will be copied.

The function returns the address of the newly unshifted item, and NULL if the item could not be unshifted.

pasprintf

Definition:

Usage:

Implementation and replacement for asprintf. pasprintf() takes only the format-string and various arguments. It outputs an allocated string to be freed later on.

fmt is the format string. ... are the parameters according to the placeholders set in fmt.

Returns a char* Returns the allocated string which contains the format string with inserted values.

pawcsprintf

Definition:

Usage:

An implementation of pasprintf() for wide-character wchar_t. pasprintf() takes only the format-string and various arguments. It outputs an allocated string to be released with pfree() later on.

fmt is the format string. ... are the parameters according to the placeholders set in fmt.

Returns a wchar_t* Returns the allocated string which cointains the format string with inserted values.

This function is only available when compiled with -DUNICODE.

pbasename

Definition:

Usage:

Returns the basename of a file.

path is the file path pointer.

Returns a pointer to the basename, which is a part of path.

pccl_add

Definition:

Usage:

Integrates a single character into a character-class.

ccl is the pointer to the character-class to be affected. ch is the character to be integrated.

The function is a shortcut for pccl_addrange().

pccl_addrange

Definition:

Usage:

Integrates a character range into a character-class.

ccl is the pointer to the character-class to be affected. If ccl is provided as (pccl*)NULL, it will be created by the function.

begin is the begin of character range to be integrated. end is the end of character range to be integrated.

If begin is greater than end, the values will be swapped.

pccl_compare

Definition:

Usage:

Checks for differences in two character-classes.

left is the pointer to the first character-class. right is the pointer to the second character-class.

Returns a value < 0 if left is lower than right, 0 if left is equal to right or a value > 0 if left is greater than right.

pccl_compat

Definition:

Usage:

Checks if the character-classes l and r are configured to be in the same character universe and compatible for operations.

pccl_count

Definition:

Usage:

Returns the number of characters within a character-class.

ccl is a pointer to the character-class to be processed.

Returns the total number of characters the class is holding.

pccl_create

Definition:

Usage:

Constructor function to create a new character-class.

min and max can either be specified as -1, so the configured default constants PCCL_MIN and PCCL_MAX will be used. The values can also be inverted.

Returns a pointer to the newly created character-class. This pointer should be released with pccl_free() when its existence is no longer required.

pccl_del

Definition:

Usage:

Removes a character from a character-class.

ccl is the pointer to the character-class to be affected. ch is the character to be removed from ccl.

The function is a shortcut for pccl_delrange().

pccl_delrange

Definition:

Usage:

Removes a character range from a character-class.

ccl is the pointer to the character-class to be affected. begin is the begin of character range to be removed. end is the end of character range to be removed.

pccl_diff

Definition:

Usage:

Returns the difference quantity of two character-classes. All elements from rem will be removed from ccl, and put into a new character-class.

ccl is the pointer to the first character-class. rem is the pointer to the second character-class.

Returns a new pointer to a copy of ccl, without the ranges contained in rem. Returns (pccl*)NULL in case of memory allocation or parameter error.

pccl_dup

Definition:

Usage:

Duplicates a character-class into a new one.

ccl is the pointer to the character-class to be duplicated.

Returns a pointer to the duplicate of ccl, or (pcrange)NULL in error case.

pccl_erase

Definition:

Usage:

Erases a character-class ccl.

The function sets a character-class to zero, as it contains no character range definitions. The object ccl will be still alive. To delete the entire object, use pccl_free().

pccl_free

Definition:

Usage:

Frees a character-class ccl and all its used memory.

The function always returns (pccl*)NULL.

pccl_get

Definition:

Usage:

Return a character or a character-range by its offset.

If the function is called only with pointer from provided, and to as (wchar_t*)NULL, it writes the character in offsetth position of the character-class into from.

If the function is called both with pointer from and to provided, it writes the begin and end character of the character-range in the offsetth position of the character-class into from and to.

If no character or range with the given offset was found, the function returns FALSE, meaning that the end of the characters is reached. On success, the function will always return TRUE.

pccl_instest

Definition:

Usage:

Tests for a character in case-insensitive-mode if it matches a character-class.

ccl is the pointer to character-class to be tested. ch is the character to be tested.

The function is a shortcut for pccl_testrange().

It returns TRUE, if the character matches the class, and FALSE if not.

pccl_intersect

Definition:

Usage:

Returns a new character-class with all characters that exist in both provided character-classes.

ccl is the pointer to the first character-class. within is the pointer to the second character-class.

Returns a new character-class containing the intersection of ccl and within. If there is no intersection between both character-classes, the function returns (pccl*)NULL.

pccl_negate

Definition:

Usage:

Negates all ranges in a character-class.

ccl is the pointer to the character-class to be negated.

Returns a pointer to ccl.

pccl_parse

Definition:

Usage:

Parses the character-class definition provided in ccldef and assigns this definition to the character-class ccl.

If ccl is NULL, a new character-class with the PCCL_MIN/PCCL_MAX configuration will be created.

ccldef may contain UTF-8 formatted input. Escape-sequences will be interpreted to their correct character representations.

A typical character-class definition simply exists of single characters and range definitions. For example, "$A-Z#0-9" defines a character-class that consists of the characters "$#0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ".

The parameter extend specifies, if the provided character-class overwrites (extend = FALSE) or extends (extend = TRUE) the provided character-class. This means that definitions that already exist in the character-class, should be erased first or not.

The function returns TRUE on success, and FALSE on an error.

pccl_parsechar

Definition:

Usage:

Reads a character from a string. The character may consist of one single character or it may be made up of an escape sequence or UTF-8 character. The function returns the number of bytes read.

retc is the return pointer for the character code of the escaped string. str is the begin pointer of the string at which character parsing begins. If escapeseq is TRUE, the function regards escape sequences, else it ignores them.

Returns the number of bytes that had been read for the character.

pccl_parseshorthand

Definition:

Usage:

Tries to parse a shorthand sequence from a string. This matches the shorthands \w, \W, \d, \D, \s and \S. If it matches, all characters are added to ccl.

The function returns TRUE in case a shorthand has been parsed. If so, the pointer str is moved the characters consumed.

If no shorthand sequence could be found, it returns FALSE, leaving ccl untouched.

pccl_print

Definition:

Usage:

Print character-class to output stream. This function is provided for debug-purposes only.

stream is the output stream to dump the character-class to; This can be left (FILE*)NULL, so stderr will be used. ccl is the pointer to character-class

break_after defines:

• if < 0 print with pointer info
• if 0 print all into one line
• if > 0 print linewise

pccl_size

Definition:

Usage:

Returns the number of range pairs within a character-class.

ccl is a pointer to the character-class to be processed.

To retrieve the number of characters in a character-class, use pccl_count() instead.

Returns the number of pairs the charclass holds.

pccl_test

Definition:

Usage:

Tests a character-class if it contains a character.

ccl is the pointer to character-class to be tested. ch is the character to be tested.

The function is a shortcut for pccl_testrange().

It returns TRUE, if the character matches the class, and FALSE if not.

pccl_testrange

Definition:

Usage:

Tests a character-class to match a character range.

ccl is a pointer to the character-class to be tested. begin is the begin of character-range to be tested. end is the end of character-range to be tested.

Returns TRUE if the entire character range matches the class, and FALSE if not.

pccl_to_str

Definition:

Usage:

Converts a character-class back to a string representation of the character-class definition, which in turn can be converted back into a character-class using pccl_create().

ccl is the pointer to character-class to be converted. escape, if TRUE, escapes "unprintable" characters in their hexadecimal representation. If FALSE, it prints all characters, except the zero, which will be returned as "\0"

Returns a pointer to the generated string that represents the charclass. The returned pointer belongs to the ccl and is managed by the character-class handling functions, so it should not be freed manually.

pccl_union

Definition:

Usage:

Creates the union of two character-classes and returns the newly created, normalized character-class.

ccl is the pointer to the character-class that will be extended to all ranges contained in add. add is the character-class that will be joined with ccl.

The function creates and returns a new character-class that is the union of ccl and add.

pdbl_to_str

Definition:

Usage:

Converts a double-value into an allocated string buffer.

d is the double value to become converted. Zero-digits behind the decimal dot will be removed after conversion, so 1.65000 will become "1.65" in its string representation.

Returns a pointer to the newly allocated string, which contains the string-representation of the double value. This pointer must be released by the caller.

pdbl_to_wcs

Definition:

Usage:

Converts a double-value into an allocated wide-character string buffer.

d is the double value to become converted. Zero-digits behind the decimal dot will be removed after conversion, so 1.65000 will become L"1.65" in its wide-character string representation.

Returns a pointer to the newly allocated wide-character string, which contains the string-representation of the double value. This pointer must be released by the caller.

This function is only available when compiled with -DUNICODE.

pfileexists

Definition:

Usage:

Checks for file existence.

filename is the path to a file that will be checked.

Returns TRUE on success, FALSE if not.

pfiletostr

Definition:

Usage:

Maps the content of an entire file into memory.

cont is the file content return pointer. filename is the path to file to be mapped

The function returns TRUE on success.

pfree

Definition:

Usage:

Free allocated memory.

The function is a wrapper for the system-function free(), but accepts NULL-pointers and returns a (void*)NULL pointer for direct pointer memory reset.

It could be used this way to immediately reset a pointer to NULL:

ptr = pfree( ptr );

ptr is the pointer to be freed.

Always returns (void*)NULL.

pgetline

Definition:

Usage:

Reads an entire line from stream, storing the address of the buffer containing the text into lineptr. The buffer is zero-terminated and includes the newline character, if one was found.

This function serves as a platform-independent implementation for POSIX getline(), which is wrapped in case of POSIX.

pgetopt

Definition:

Usage:

Command-line option interpreter.

This function works similar to the getopt() functions of the GNU Standard Library, but uses a different style of parameter submit.

It supports both short- and long- option-style parameters.

• opt is a pointer to a buffer with enough space to store the requested parameter to. For short parameters, this is only one char, for long-parameters the full name. The string will be zero-terminated.
• param is a pointer to store a possible parameter value to, if the detected option allows for parameters.
• next receives the index in argv of the next evaluated option. It can be left (int*)NULL. It points to the next valid index in argv[] after all parameters have been evaluated. Check it for < argc, to point to valid data.
• argc is the argument count as taken from the main() function.
• argv are the argument values as taken from the main() function.
• optstr contains the possible short-options. This is a string where each character defines an option. If an option takes a parameter, a colon (:) is submitted. E.g. "abc:def:g". The Options "-c" and "-f" will take a parameter that is returned to param. This parameter can be (char*)NULL.
• loptstr contains the possible long-options. This is a string containing all long option names, each separated by a blank. Long options taking parameters have an attached colon (:) to the name. E.g. "hello world: next" defines three long options, where option 'world' takes one parameter that is returned to param. This parameter can be (char*)NULL.
• idx is the index of the requested option, 0 for the first option behind argv[0].

The function must be called multiple times to read all command-line parameters and to react on the parameters.

The function returns 0, if the parameter with the given index was successfully evaluated. It returns 1, if there are still command-line parameters, but not as part of options. The parameter param will receive the given pointer. It returns -1 if no more options could be read, or if an option could not be evaluated (unknown option). In such case, param will hold a string to the option that is unknown to pgetopt().

Example:

This is a minimal example showing the usage of pgetopt() in a real program:

#include <phorward.h>

int main( int argc, char** argv )
{
    int			i;
    int			rc;
    int			next;
    char		opt			[ 10 + 1 ];
    char*		param;

    for( i = 0; ( rc = pgetopt( opt, &param, &next, argc, argv,
                                "ho:", "help output:", i ) ) == 0; i++ )
    {
        if( !strcmp( opt, "help" ) || !strcmp( opt, "h" ) )
            printf( "Help\n" );
        else if( !strcmp( opt, "output" ) || !strcmp( opt, "o" ) )
            printf( "Output = >%s<\n", param );
    }

    if( rc < 0 && param )
    {
        fprintf( stderr, "Unknown option '%s'\n", param );
        return 1;
    }

    for( i = 0; next < argc; next++, i++ )
        printf( "Parameter %d = >%s<\n", i, argv[ next ] );

    return 0;
}

plex_create

Definition:

Usage:

Constructor function to create a new plex object.

flags can be a combination of compile- and runtime-flags and are merged with special compile-time flags provided for each pattern.

On success, the function returns the allocated pointer to a plex-object. This must be freed later using plex_free().

plex_define

Definition:

Usage:

Defines and parses a regular expression pattern into the plex-object.

pat is the regular expression string, or a pointer to a pregex_ptn* structure in case PREGEX_COMP_PTN is flagged.

match_id must be a token match ID, a value > 0. The lower the match ID is, the higher precedence takes the appended expression when there are multiple matches.

flags may ONLY contain compile-time flags, and is combined with the compile-time flags of the plex-object provided at plex_create().

Returns a pointer to the pattern object that just has been added. This allows for changing e.g. the accept flag later on. In case of an error, the value returned is NULL.

plex_dump_dot

Definition:

Usage:

Dumps the DFA of a lex lexer object into a DOT-formatted graph output.

The graph can be made visible with tools like Graphviz (http://www.graphviz.org/) and similar.

stream is the output stream to be used. This is stdout when NULL is provided.

lex is the plex object, which DFA shall be dumped.

plex_free

Definition:

Usage:

Destructor function for a plex-object.

lex is the pointer to a plex-structure that will be released.

Always returns (plex*)NULL.

plex_lex

Definition:

Usage:

Performs a lexical analysis using the object lex on pointer start.

If a token can be matched, the function returns the related id of the matching pattern, and end receives the pointer to the last matched character.

The function returns 0 in case that there was no direct match. The function plex_next() ignores unrecognized symbols and directly moves to the next matching pattern.

plex_next

Definition:

Usage:

Performs lexical analysis using lex from begin of pointer start, to the next matching token.

start has to be a zero-terminated string or wide-character string (according to the configuration of the plex-object).

If a token can be matched, the function returns the pointer to the position where the match starts at. id receives the id of the matching pattern, end receives the end pointer of the match, when provided. id and end can be omitted by providing NULL-pointers.

The function returns (char*)NULL in case that there is no match.

plex_prepare

Definition:

Usage:

Prepares the DFA state machine of a plex-object lex for execution.

plex_reset

Definition:

Usage:

Resets the DFA state machine of a plex-object lex.

plex_tokenize

Definition:

Usage:

Tokenizes the string beginning at start using the lexical analyzer lex.

start has to be a zero-terminated string or wide-character string (according to the configuration of the plex-object).

The function initializes and fills the array matches, if provided, with items of size prange. It returns the total number of matches.

plexctx_create

Definition:

Usage:

Creates a new lexer context for lexer par.

lexer contexts are objects holding state and semantics information on a current parsing process.

plexctx_free

Definition:

Usage:

Frees the lexer context object ctx.

plexctx_init

Definition:

Usage:

Initializes a lexer context ctx for lexer lex.

Lexer contexts are objects holding state and semantics information on a current lexing process.

plexctx_lex

Definition:

Usage:

Performs a lexical analysis using the object lex using context ctx and character ch.

plexctx_reset

Definition:

Usage:

Resets the lexer context object ctx.

plist_access

Definition:

Usage:

Access data-content of the current element e.

plist_clear

Definition:

Usage:

Clear content of the list list.

The function has nearly the same purpose as plist_erase(), except that the entire list is only cleared, but if the list was initialized with PLIST_MOD_RECYCLE, existing pointers are held for later usage.

plist_concat

Definition:

Usage:

Concats the elements of list src to the elements of list dest.

The function will not run if both lists have different element size settings.

The function returns the number of elements added to dest.

plist_count

Definition:

Usage:

Return element count of list l.

plist_create

Definition:

Usage:

Create a new plist as an object with an element allocation size size. Providing a size of 0 causes automatic configuration of PLIST_MOD_PTR.

flags defines an optional flag configuration that modifies the behavior of the linked list and hash table usage. The flags can be merged together using bitwise or (|).

Possible flags are:

• PLIST_MOD_NONE for no special flagging.
• PLIST_MOD_PTR to use the plist-object in pointer-mode: Each plistel-element cointains only a pointer to an object in the memory and returns this, instead of copying from or into pointers.
• PLIST_MOD_RECYCLE to configure that elements that are removed during list usage will be reused later.
• PLIST_MOD_AUTOSORT to automatically sort elements on insert operations.
• PLIST_MOD_EXTKEYS to configure that string pointers to hash-table keyvalues are stored elsewhere, so the plist-module only uses the original pointers instead of copying them.
• PLIST_MOD_PTRKEYS disables string keys and uses the pointer/value provided as key directly.
• PLIST_MOD_KEEPKEYS holds the correct element insertation sequence. In case of a key collision, the inserted element is inserted behind the colliding element rather than before.
• PLIST_MOD_UNIQUE to disallow hash-table-key collisions, so elements with a key that already exist in the object will be rejected.
• PLIST_MOD_WCHAR to handle all key values as wide-character strings.

Use plist_free() to erase and release the returned list object.

plist_dbgstats

Definition:

Usage:

Prints some statistics for the hashmap in list on stderr.

plist_diff

Definition:

Usage:

Tests the contents (data parts) of the list left and the list right for equal elements.

The function returns a value < 0 if left is lower right, a value > 0 if left is greater right and a value == 0 if left is equal to right.

plist_dup

Definition:

Usage:

Creates an independent copy of list and returns it.

All elements of list are duplicated and stand-alone.

plist_erase

Definition:

Usage:

Erase all allocated content of the list list.

The object list will be still alive, but must be re-configured using plist_init().

plist_first

Definition:

Usage:

Return first element of list l.

plist_free

Definition:

Usage:

Releases all the memory list uses and destroys the list object.

The function always returns (plist*)NULL.

plist_get

Definition:

Usage:

Retrieve list element by its index from the begin.

The function returns the nth element of the list list.

plist_get_by_key

Definition:

Usage:

Retrieve list element by hash-table key.

This function tries to fetch a list entry plistel from list list with the key key.

plist_get_by_nkey

Definition:

Usage:

Retrieve list element by hash-table key, where key is limited by n bytes.

This function tries to fetch a list entry plistel from list list with the key key over a size of n bytes.

plist_get_by_ptr

Definition:

Usage:

Retrieve list element by pointer.

This function returns the list element of the unit within the list list that is the pointer ptr.

plist_getkey

Definition:

Usage:

Retrieve list keys by their index from the begin.

The function returns the nth key within the list list.

plist_hashnext

Definition:

Usage:

Access next element with same hash value of current unit u.

plist_hashprev

Definition:

Usage:

Access previous element with same hash value of a current unit u.

plist_init

Definition:

Usage:

Initialize the list list with an element allocation size size.

flags defines an optional flag configuration that modifies the behavior of the linked list and hash table usage.

plist_insert

Definition:

Usage:

Insert src as element to the list list before position pos.

If pos is NULL, the new element will be attached to the end of the list.

If key is not NULL, the element will also be added to the lists hash table.

If src is NULL, a zero-initialized element is inserted into the list for further processing.

plist_iter

Definition:

Usage:

Iterates over list.

Iterates over all items of list and calls the function callback on every item. The callback function receives the plistel-element pointer of the list element.

plist_iter_access

Definition:

Usage:

Iterates over list and accesses every item.

Iterates over all items of list and calls the function callback on every item's access. The callback function receives a pointer to the accessed element.

plist_key

Definition:

Usage:

Access key-content of the current element e.

plist_last

Definition:

Usage:

Return last element of list l.

plist_malloc

Definition:

Usage:

Allocates memory for a new element in list list, push it to the end and return the pointer to this.

The function works as a shortcut for plist_access() in combination with plist_push().

plist_next

Definition:

Usage:

Access next element of current unit u.

plist_offset

Definition:

Usage:

Return the offset of the unit u within the list it belongs to.

plist_pop

Definition:

Usage:

Pop last element to dest off the list list.

Like list would be a stack, the last element of the list is popped and its content is written to dest, if provided at the end of the list.

dest can be omitted and given as (void*)NULL, so the last element will be popped off the list and discards.

plist_prev

Definition:

Usage:

Access previous element of current unit u.

plist_push

Definition:

Usage:

Push src to end of list.

Like list would be a stack, src is pushed at the end of the list. This function can only be used for linked lists without the hash-table feature in use.

plist_remove

Definition:

Usage:

Removes the element e from the list and frees it or puts it into the unused element chain if PLIST_MOD_RECYCLE is flagged.

plist_rget

Definition:

Usage:

Retrieve list element by its index from the end.

The function returns the nth element of the list list from the right.

plist_riter

Definition:

Usage:

Iterates backwards over list.

Backwardly iterates over all items of list and calls the function callback on every item. The callback function receives the plistel-element pointer of the list element.

plist_riter_access

Definition:

Usage:

Iterates backwards over list.

Backwardly iterates over all items of list and calls the function callback on every item's access. The callback function receives a pointer to the accessed element.

plist_rmalloc

Definition:

Usage:

Allocates memory for a new element in list list, shift it at the begin and return the pointer to this.

The function works as a shortcut for plist_access() in combination with plist_shift().

plist_set_comparefn

Definition:

Usage:

Set compare function.

If no compare function is set or NULL is provided, memcmp() will be used as default fallback.

plist_set_printfn

Definition:

Usage:

Set an element dump function.

plist_set_sortfn

Definition:

Usage:

Set sort function.

If no sort function is given, the compare function set by plist_set_comparefn() is used. If even unset, memcmp() will be used.

plist_shift

Definition:

Usage:

Shift src at begin of list.

Like list would be a queue, src is shifted at the beginning of the list. This function can only be used for linked lists without the hash-table feature in use.

plist_size

Definition:

Usage:

Return element size of list l.

plist_sort

Definition:

Usage:

Sorts list according to the sort-function that was set for the list.

To sort only parts of a list, use plist_subsort().

The sort-function can be modified by using plist_set_sortfn().

The default sort function sorts the list by content using the memcmp() standard function.

plist_subsort

Definition:

Usage:

Sorts list between the elements from and to according to the sort-function that was set for the list.

To sort the entire list, use plist_sort().

The sort-function can be modified by using plist_set_sortfn().

The default sort function sorts the list by content using the memcmp() standard function.

plist_swap

Definition:

Usage:

Swaps the positions of the list elements a and b with each other. The elements must be in the same plist object, else the function returns FALSE.

plist_union

Definition:

Usage:

Unions elements from list from into list all.

An element is only added to all, if there exists no equal element with the same size and content.

The function will not run if both lists have different element size settings.

The function returns the number of elements added to from.

plist_unshift

Definition:

Usage:

Take first element of list and write it to dest.

Like list would be a queue, the first element of the list is taken and its content is written to dest.

dest can be omitted and given as (void*)NULL, so the first element from list will be taken and discarded.

pmalloc

Definition:

Usage:

Dynamically allocate heap memory.

The function is a wrapper for the system function malloc(), but with memory initialization to zero, and immediately stops the program if no more memory can be allocated.

size is the size of memory to be allocated, in bytes.

The function returns the allocated heap memory pointer. The returned memory address should be freed using pfree() after it is not required anymore.

pmemdup

Definition:

Usage:

Duplicates a memory entry onto the heap.

ptr is the pointer to the memory to be duplicated. size is the size of pointer's data storage.

Returns the new pointer to the memory copy. This should be cast back to the type of ptr again.

prealloc

Definition:

Usage:

Dynamically (re)allocate memory on the heap.

The function wraps the system-function realloc(), but always accepts a NULL-pointer and immediately stops the program if no more memory can be allocated.

oldptr is the pointer to be reallocated. If this is (void*)NULL, prealloc() works like a normal call to pmalloc().

size is the size of memory to be reallocated, in bytes.

The function returns the allocated heap memory pointer. The returned memory address should be freed using pfree() after it is not required any more.

pregex_create

Definition:

Usage:

Constructor function to create a new pregex object.

pat is a string providing a regular expression pattern. flags can be a combination of compile- and runtime-flags.

On success, the function returns the allocated pointer to a pregex-object. This must be freed later using pregex_free().

pregex_find

Definition:

Usage:

Find a match for the regular expression regex from begin of pointer start.

start has to be a zero-terminated string or wide-character string (according to the configuration of the pregex-object).

If the expression can be matched, the function returns the pointer to the position where the match begins. end receives the end pointer of the match, when provided.

The function returns (char*)NULL in case that there is no match.

pregex_findall

Definition:

Usage:

Find all matches for the regular expression regex from begin of pointer start, and optionally return matches as an array.

start has to be a zero-terminated string or wide-character string (according to the configuration of the pregex-object).

The function fills the array matches, if provided, with items of size prange. It returns the total number of matches.

pregex_free

Definition:

Usage:

Destructor function for a pregex-object.

regex is the pointer to a pregex-structure that will be released.

Returns always (pregex*)NULL.

pregex_match

Definition:

Usage:

Tries to match the regular expression regex at pointer start.

If the expression can be matched, the function returns TRUE and end receives the pointer to the last matched character.

pregex_ptn_create

Definition:

Usage:

Constructs and parses a new pregex_ptn-structure from pat.

This function is a shortcut for a call to pregex_ptn_parse(). pregex_ptn_create() directly takes pat as its input and returns the parsed pregex_ptn structure which represents the internal representation of the regular expression pat.

flags provides a combination of compile-time modifier flags (PREGEX_COMP_...) if wanted, or 0 (PREGEX_FLAG_NONE) if no flags should be used.

Returns an allocated pregex_ptn-node which must be freed using pregex_ptn_free() when it is not used anymore.

pregex_ptn_create_alt

Definition:

Usage:

Constructs alternations of multiple patterns.

left is the first pattern of the alternation. ... are multiple pregex_ptn-pointers follow which become part of the alternation. The last node must be specified as (pregex_ptn*)NULL.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence. If there is only left assigned without other alternation patterns, left will be returned back.

pregex_ptn_create_char

Definition:

Usage:

Constructs a character-class pattern.

ccl is the pointer to a character class. This pointer is not duplicated, and will be directly assigned to the object.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_kle

Definition:

Usage:

Constructs a kleene-closure repetition, allowing for multiple or none repetitions of the specified pattern.

ptn is the pattern that will be configured for kleene-closure.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_opt

Definition:

Usage:

Constructs an optional-closure, allowing for one or none specified pattern.

ptn is the pattern to be configured for optional closure.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_pos

Definition:

Usage:

Constructs an positive-closure, allowing for one or multiple specified pattern.

ptn is the pattern to be configured for positive closure.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_refsub

Definition:

Usage:

Constructs a sub-pattern as backreference (like with parantheses).

ptn is the pattern that becomes the sub-ordered pattern.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_seq

Definition:

Usage:

Constructs a sequence of multiple patterns.

first is the beginning pattern of the sequence. ... follows as parameter list of multiple patterns that become part of the sequence. The last pointer must be specified as (pregex_ptn*)NULL to mark the end of the list.

Always returns the pointer to first.

pregex_ptn_create_string

Definition:

Usage:

Constructs a pattern for a static string.

str is the input string to be converted. flags are optional flags for wide-character support.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_create_sub

Definition:

Usage:

Constructs a sub-pattern (like with parantheses).

ptn is the pattern that becomes the sub-ordered pattern.

Returns a pregex_ptn-node which can be child of another pattern construct or part of a sequence.

pregex_ptn_dup

Definition:

Usage:

Duplicate ptn into a stand-alone 1:1 copy.

pregex_ptn_free

Definition:

Usage:

Releases memory of a pattern including all its subsequent and following patterns.

ptn is the pattern object to be released.

Always returns (pregex_ptn*)NULL.

pregex_ptn_parse

Definition:

Usage:

Parse a regular expression pattern string into a pregex_ptn structure.

ptn is the return pointer receiving the root node of the generated pattern.

str is the pointer to the string which contains the pattern to be parsed. If PREGEX_COMP_WCHAR is assigned in flags, this pointer must be set to a wchar_t-array holding a wide-character string.

flags provides compile-time modifier flags (PREGEX_COMP_...).

Returns TRUE on success.

pregex_ptn_print

Definition:

Usage:

A debug function to print a pattern's hierarchical structure to stderr.

ptn is the pattern object to be printed. rec is the recursion depth, set this to 0 at initial call.

pregex_ptn_to_dfa

Definition:

Usage:

Converts a pattern-structure into a DFA state machine.

dfa is the DFA state machine structure that receives the compiled result of the pattern. dfa must be initialized! ptn is the pattern structure that will be converted and extended into the DFA state machine.

Returns TRUE on success.

pregex_ptn_to_dfatab

Definition:

Usage:

Converts a pattern-structure into a DFA state machine dfatab.

ptn is the pattern structure that will be converted into a DFA state machine.

dfatab is a pointer to a variable that receives the allocated DFA state machine, where each row forms a state that is made up of columns described in the table below.

Example for a state machine that matches the regular expression @[a-z0-9]+ that has match 1 and no references:

8 0 0 0 3 64 64 2
11 1 0 0 3 48 57 1 97 122 1
11 0 0 0 3 48 57 1 97 122 1

Interpretation:

00: col= 8 acc= 0 flg= 0 ref= 0 def= 3 tra=064(@);064(@):02
01: col=11 acc= 1 flg= 0 ref= 0 def= 3 tra=048(0);057(9):01 tra=097(a);122(z):01
02: col=11 acc= 0 flg= 0 ref= 0 def= 3 tra=048(0);057(9):01 tra=097(a);122(z):01

A similar dump like this interpretation above will be printed to stderr by the function when dfatab is provided as (long***)NULL.

The pointer assigned to dfatab must be freed after usage using a for-loop:

for( i = 0; i < dfatab_cnt; i++ )
	pfree( dfatab[i] );

pfree( dfatab );

Returns the number of rows in dfatab, or a negative value in error case.

pregex_ptn_to_nfa

Definition:

Usage:

Converts a pattern-structure into a NFA state machine.

nfa is the NFA state machine structure that receives the compiled result of the pattern. This machine will be extended to the pattern if it already contains states. nfa must be previously initialized!

ptn is the pattern structure that will be converted and extended into the NFA state machine.

flags are compile-time flags.

Returns TRUE on success.

pregex_ptn_to_regex

Definition:

Usage:

Turns a regular expression pattern back into a regular expression string.

ptn is the pattern object to be converted into a regex.

The returned pointer is dynamically allocated but part of ptn, so it should not be freed by the caller. It is automatically freed when the pattern object is released.

pregex_qmatch

Definition:

Usage:

Performs a regular expression match on a string, and returns an array of matches via prange-structures, which hold pointers to the begin- and end-addresses of all matches.

regex is the regular expression pattern to be processed.

str is the string on which the pattern will be executed.

flags are for regular expression compile- and runtime-mode switching. Several of them can be used with the bitwise or-operator (|).

matches is the array of results to the matched substrings within str, provided as parray-object existing of one prange-object for every match. It is optional. matches must be released with parray_free() after its usage.

Returns the number of matches, which is the number of result entries in the returned array matches. If the value is negative, an error occurred.

pregex_qreplace

Definition:

Usage:

Replaces all matches of a regular expression pattern within a string with the replacement. Backreferences can be used with $x for each opening bracket within the regular expression.

regex is the regular expression pattern to be processed.

str is the string on which the pattern will be executed.

replace is the string that will be inserted as replacement for each pattern match. $x back-references can be used.

flags are for regular expression compile- and runtime-mode switching. Several of them can be used with the bitwise or-operator (|).

Returns an allocated pointer to the generated string with the replacements. This string must be released after its existence is no longer required by the caller using pfree().

pregex_qsplit

Definition:

Usage:

Performs a regular expression search on a string and uses the expression as separator; All strings that where split are returned as matches-array.

regex is the regular expression pattern to be processed.

str is the string on which the pattern will be executed.

flags are for regular expression compile- and runtime-mode switching. Several of them can be used with the bitwise or-operator (|).

matches is the array of results to the matched substrings within str, provided as parray-object existing of one prange-object for every match. It is optional. matches must be released with parray_free() after its usage.

Returns the number of split substrings, which is the number of result entries in the returned array matches. If the value is negative, an error occured.

pregex_replace

Definition:

Usage:

Replaces all matches of a regular expression object within a string str with replacement. Backreferences in replacement can be used with $x for each opening bracket within the regular expression.

regex is the pregex-object used for pattern matching. str is the string on which regex will be executed. replacement is the string that will be inserted as the replacement for each match of a pattern described in regex. The notation $x can be used for backreferences, where x is the offset of opening brackets in the pattern, beginning at 1.

The function returns the string with the replaced elements, or (char*)NULL in case of an error.

pregex_split

Definition:

Usage:

Returns the range between string start and the next match of regex.

This function can be seen as a "negative match", so the substrings that are not part of the match will be returned.

start has to be a zero-terminated string or wide-character string (according to the configuration of the pregex-object). end receives the last position of the string before the regex. next receives the pointer of the next split element behind the matched substring, so next should become the next start when pregex_split() is called in a loop.

The function returns (char*)NULL in case there is no more string to split, else it returns start.

pregex_splitall

Definition:

Usage:

Split a string at all matches of the regular expression regex from begin of pointer start, and optionally returns the substrings found as an array.

start has to be a zero-terminated string or wide-character string (according to the configuration of the pregex-object).

The function fills the array matches, if provided, with items of size prange. It returns the total number of matches.

pstr_to_wcs

Definition:

Usage:

This functions converts an UTF-8-multi-byte string into a Unicode wide-character string.

The function wraps mbstowcs(), so set_locale() must be done before this function works properly.

str is the zero-terminated multi-byte-character string to be converted into a wide-character string. freestr if value equals TRUE then str will be freed after successfull conversion.

Returns the wide-character pendant of str as pointer to dynamically allocated memory.

pstrcasecmp

Definition:

Usage:

Compare a string ignoring case-order.

s1 is the string to compare with s2. s2 is the string to compare with s1.

Returns 0 if both strings are equal. Returns a value <0 if s1 is lower than s2 or a value >0 if s1 is greater than s2.

pstrcatchar

Definition:

Usage:

Dynamically appends a character to a string.

str is the pointer to a string to be appended. If this is (char*)NULL, the string will be newly allocated. chr is the character to be appended to str.

Returns a char*-pointer to the (possibly re-)allocated and appended string. (char*)NULL is returned if no memory could be (re)allocated. This pointer must be released with pfree() when its existence is no longer required.

pstrcatstr

Definition:

Usage:

Dynamically appends a zero-terminated string to a dynamic string.

str is the pointer to a zero-terminated string to be appended. If this is (char*)NULL, the string is newly allocated.

append is the string to be appended at the end of str.

freesrc frees the pointer provided as append automatically by this function, if set to TRUE.

Returns a char*-pointer to (possibly re-)allocated and appended string. (char*)NULL is returned if no memory could be (re)allocated, or both strings were NULL. If dest is NULL and freesrc is FALSE, the function automatically returns the pointer src. This pointer must be released with pfree() when its existence is no longer required.

pstrdup

Definition:

Usage:

Duplicate a string in memory.

str is the string to be copied in memory. If str is provided as NULL, the function will also return NULL.

Returns a char*-pointer to the newly allocated copy of str. This pointer must be released with pfree() when its existence is no longer required.

pstrget

Definition:

Usage:

Safely reads a string.

str is the string pointer to be safely read. If str is NULL, the function returns a pointer to a static address holding an empty string.

pstrlen

Definition:

Usage:

Return length of a string.

str is the parameter string to be evaluated. If (char*)NULL, the function returns 0. pstrlen() is much safer than strlen() because it returns 0 when a NULL-pointer is provided.

Returns the length of the string str.

pstrltrim

Definition:

Usage:

Removes whitespace on the left of a string.

s is the string to be left-trimmed.

Returns s.

pstrlwr

Definition:

Usage:

Convert a string to lower-case.

s is the acts both as input and output-string.

Returns s.

pstrncasecmp

Definition:

Usage:

Compare two strings ignoring case-order up to a maximum of n bytes.

s1 is the string to compare with s2. s2 is the string to compare with s1. n is the number of bytes to compare.

Returns 0 if both strings are equal. Returns a value <0 if s1 is less than s2 or a value >0 if s1 is greater than s2.

pstrncatstr

Definition:

Usage:

Dynamically appends n-characters from one string to another string.

The function works similar to pstrcatstr(), but allows to copy only a maximum of n characters from append.

str is the pointer to a string to be appended. If this is (char*)NULL, the string is newly allocated. append is the begin of character sequence to be appended. n is the number of characters to be appended to str.

Returns a char*-pointer to (possibly re-)allocated and appended string. (char*)NULL is returned if no memory could be (re)allocated, or both strings were NULL. This pointer must be released with pfree() when its existence is no longer required.

pstrndup

Definition:

Usage:

Duplicate n characters from a string in memory.

The function mixes the functionalities of strdup() and strncpy(). The resulting string will be zero-terminated.

str is the parameter string to be duplicated. If this is provided as (char*)NULL, the function will also return (char*)NULL. n is the number of characters to be copied and duplicated from str. If n is greater than the length of str, copying will stop at the zero terminator.

Returns a char*-pointer to the allocated memory holding the zero-terminated string duplicate. This pointer must be released with pfree() when its existence is no longer required.

pstrput

Definition:

Usage:

Assign a string to a dynamically allocated pointer. pstrput() manages the assignment of a dynamically allocated string.

str is a pointer receiving the target pointer to be (re)allocated. If str already references a string, this pointer will be freed and reassigned to a copy of val.

val is the string to be assigned to str (as a independent copy).

Returns a pointer to the allocated heap memory on success, (char*)NULL else. This is the same pointer as returned when calling *str. The returned pointer must be released with pfree() or another call of pstrput(). Calling pstrput() as pstrput( &p, (char*)NULL ); is equivalent to p = pfree( &p ).

pstrrender

Definition:

Usage:

String rendering function.

Inserts multiple values dynamically into the according wildcards positions of a template string. The function can be compared to the function of pstrreplace(), but allows to replace multiple substrings by multiple replacement strings.

tpl is the template string to be rendered with values. ... are the set of values to be inserted into the desired position;

These consist of three values each:

• char* name as a wildcard-name
• char* value as the replacement value for the wildcard
• pboolean freeflag defines if value shall be freed after processing

Returns an allocated string which is the result of rendering. This string must be released by pfree() or another function releasing heap memory when its existence is no longer required.

pstrreplace

Definition:

Usage:

Replace a substring sequence within a string.

str is the string to be replaced in. find is the substring to be matched. replace is the string to be inserted for each match of the substring find.

Returns a char* containing the allocated string which is the result of replacing all occurences of find with replace in str.

This pointer must be released with pfree() when its existence is no longer required.

pstrrtrim

Definition:

Usage:

Removes trailing whitespace on the right of a string.

s is the string to be right-trimmed.

Returns s.

pstrsplit

Definition:

Usage:

Splits a string at a delimiting token and returns an allocated array of token reference pointers.

tokens is an allocated array of tokenized array values. Requires a pointer to char**. str is the input string to be tokenized. sep is the token separation substring. limit is the token limit; If set to 0, there is no token limit available, in which case as many as possible tokens are read.

Returns the number of separated tokens, or -1 on error.

pstrtrim

Definition:

Usage:

Removes beginning and trailing whitespace from a string.

s is the string to be trimmed.

Returns s.

pstrunescape

Definition:

Usage:

Converts a string with included escape-sequences back into its natural form.

The following table shows escape sequences which are converted.

The replacement is done within the memory bounds of str itself, because the unescaped version of the character requires less space than its previous escape sequence.

The function always returns its input pointer.

Example:

char* s = (char*)NULL;

psetstr( &s, "\\tHello\\nWorld!" );
printf( ">%s<\n", pstrunescape( s ) );

s = pfree( s );

pstrupr

Definition:

Usage:

Convert a string to upper-case.

s acts both as input- and output string.

Returns s.

putf8_char

Definition:

Usage:

Return single character (as wide-character value) from UTF-8 multi-byte character string.

str is the pointer to character sequence begin.

putf8_isutf

Definition:

Usage:

Check for UTF-8 character sequence signature.

The function returns TRUE, if the character c is the beginning of a UTF-8 character signature, else FALSE.

putf8_move

Definition:

Usage:

Moves count characters ahead in an UTF-8 multi-byte character sequence.

str is the pointer to UTF-8 string to begin moving. count is the number of characters to move left.

The function returns the address of the next UTF-8 character sequence after count characters. If the string's end is reached, it will return a pointer to the zero-terminator.

putf8_parse_char

Definition:

Usage:

Read one character from an UTF-8 input sequence. This character can be escaped, an UTF-8 character or an ordinary ASCII-char.

chr is the input- and output-pointer (the pointer is replaced by the pointer to the next character or escape-sequence within the string).

The function returns the character code of the parsed character.

putf8_seqlen

Definition:

Usage:

Returns length of next UTF-8 sequence in a multi-byte character string.

s is the pointer to begin of UTF-8 sequence.

Returns the number of bytes used for the next character.

pvasprintf

Definition:

Usage:

Implementation and replacement for vasprintf.

str is the pointer receiving the result, allocated string pointer. fmt is the format string. ... are the parameters according to the placeholders set in fmt.

Returns the number of characters written, or -1 in case of an error.

pvawcsprintf

Definition:

Usage:

Wide-character implementation of pasprintf().

str is the a pointer receiving the resultung, allocated string pointer. fmt is the the format string. ... is the parameters according to the placeholders set in fmt.

Returns the number of characters written.

This function is only available when compiled with -DUNICODE.

pwcs_to_str

Definition:

Usage:

This functions converts a wide-character string into an UTF-8 string.

The string conversion is performed into dynamically allocated memory. The function wraps the system function wcstombs(), so set_locale() must be called before this function works properly.

str is the zero-terminated string to be converted to UTF-8. freestr defines if the input-string shall be freed after successful conversion, if set to TRUE.

Returns the UTF-8 character pendant of str as pointer to dynamically allocated memory.

pwcscatchar

Definition:

Usage:

Appends a character to a dynamic wide-character string.

str is the pointer to a wchar_t-string to be appended. If this is (wchar_t*)NULL, the string is newly allocated. chr is the the character to be appended to str.

Returns a wchar_t* Pointer to (possibly re-)allo- cated and appended string. (wchar_t*)NULL is returned if no memory could be (re)allocated.

This function is only available when compiled with -DUNICODE.

pwcscatstr

Definition:

Usage:

Appends a (possibly dynamic) wide-character string to a dynamic wide-character string.

str is the pointer to a wchar_t-string to be appended. If this is (wchar_t*)NULL, the string is newly allocated. append is the string to be appended. freesrc if true, append is free'd automatically by this function.

Returns a wchar_t* Pointer to (possibly re-)allo- cated and appended string. (wchar_t*)NULL is returned if no memory could be (re)allocated, or both strings were NULL.

This function is only available when compiled with -DUNICODE.

pwcsdup

Definition:

Usage:

Duplicate a wide-character string in memory.

str is the string to be copied in memory. If str is provided as NULL, the function will also return NULL.

Returns a wchar_t*-pointer to the newly allocated copy of str. This pointer must be released with pfree() when its existence is no longer required.

This function is only available when compiled with -DUNICODE.

pwcsget

Definition:

Usage:

Safely reads a wide-character string.

str is the string pointer to be safely read. If str is NULL, the function returns a pointer to a static address holding an empty string.

This function is only available when compiled with -DUNICODE.

pwcslen

Definition:

Usage:

Safe strlen replacement for wide-character.

str is the parameter string to be evaluated. If (wchar_t*)NULL, the function returns 0.

This function is only available when compiled with -DUNICODE.

pwcsncatstr

Definition:

Usage:

Appends n characters from one wide-character string to a dynamic string.

str is the pointer to a wchar_t-string to be appended. If this is (wchar_t*)NULL, the string is newly allocated. append is the begin of character sequence to be appended. n is the number of characters to be appended to str.

Returns a wchar_t* Pointer to (possibly re-)allo- cated and appended string. (wchar_t*)NULL is returned if no memory could be (re)allocated, or both strings were NULL.

This function is only available when compiled with -DUNICODE.

pwcsndup

Definition:

Usage:

Duplicate n characters from a wide-character string in memory.

The function mixes the functionalities of wcsdup() and wcsncpy(). The resulting wide-character string will be zero-terminated.

str is the parameter wide-character string to be duplicated. If this is provided as (wchar_t*)NULL, the function will also return (wchar_t*)NULL.

n is the the number of characters to be copied and duplicated from str. If n is greater than the length of str, copying will stop at the zero terminator.

Returns a wchar_t*-pointer to the allocated memory holding the zero-terminated wide-character string duplicate. This pointer must be released with pfree() when its existence is no longer required.

This function is only available when compiled with -DUNICODE.

pwcsput

Definition:

Usage:

Assign a wide-character string to a dynamically allocated pointer. pwcsput() manages the assignment of an dynamically allocated wide-chararacter string.

str is a pointer receiving the target pointer to be (re)allocated. If str already references a wide-character string, this pointer will be freed and reassigned to a copy of val.

val is the the wide-character string to be assigned to str (as an independent copy).

Returns a pointer to the allocated heap memory on success, (char_t*)NULL else. This is the same pointer as returned when calling *str. The returned pointer must be released with pfree() or another call of pwcsput(). Calling pwcsput() as pwcsput( &p, (char*)NULL ); is equivalent to p = pfree( &p ).

This function is only available when compiled with -DUNICODE.

pwhich

Definition:

Usage:

Figures out a filepath by searching in a PATH definition.

filename is the filename to be searched for.

directories is a string specifying the directories to search in. If this is (char*)NULL, the environment variable PATH will be used and evaluated by using getenv() #fn_getenv]. The path can be split with multiple paths by a character that depends on the current platform (Unix: ":", Windows: ";").

Returns a static pointer to the absolute path that contains the file specified as filename, else it will return (char*)NULL.