Static String Functions.

Replacements for the standard C string functions. More...

Functions
TRIO_STRING_PUBLIC char *	trio_create (size_t size)
	Create new string. More...
TRIO_STRING_PUBLIC void	trio_destroy (char *string)
	Destroy string. More...
TRIO_STRING_PUBLIC size_t	trio_length (const char *string)
	Count the number of characters in a string. More...
TRIO_STRING_PUBLIC int	trio_append (char target, const char source)
	Append `source` at the end of `target`. More...
TRIO_STRING_PUBLIC int	trio_append_max (char target, size_t max, const char source)
	Append at most `max` characters from `source` to `target`. More...
TRIO_STRING_PUBLIC int	trio_contains (const char string, const char substring)
	Determine if a string contains a substring. More...
TRIO_STRING_PUBLIC int	trio_copy (char target, const char source)
	Copy `source` to `target`. More...
TRIO_STRING_PUBLIC int	trio_copy_max (char target, size_t max, const char source)
	Copy at most `max` characters from `source` to `target`. More...
TRIO_STRING_PUBLIC char *	trio_duplicate (const char *source)
	Duplicate `source`. More...
TRIO_STRING_PUBLIC char *	trio_duplicate_max (const char *source, size_t max)
	Duplicate at most `max` characters of `source`. More...
TRIO_STRING_PUBLIC int	trio_equal (const char first, const char second)
	Compare if two strings are equal. More...
TRIO_STRING_PUBLIC int	trio_equal_case (const char first, const char second)
	Compare if two strings are equal. More...
TRIO_STRING_PUBLIC int	trio_equal_case_max (const char first, size_t max, const char second)
	Compare if two strings up until the first `max` characters are equal. More...
TRIO_STRING_PUBLIC int	trio_equal_locale (const char first, const char second)
	Compare if two strings are equal. More...
TRIO_STRING_PUBLIC int	trio_equal_max (const char first, size_t max, const char second)
	Compare if two strings up until the first `max` characters are equal. More...
TRIO_STRING_PUBLIC const char *	trio_error (int error_number)
	Provide a textual description of an error code (errno). More...
TRIO_STRING_PUBLIC size_t	trio_format_date_max (char target, size_t max, const char format, const struct tm *datetime)
	Format the date/time according to `format`. More...
TRIO_STRING_PUBLIC unsigned long	trio_hash (const char *string, int type)
	Calculate a hash value for a string. More...
TRIO_STRING_PUBLIC char *	trio_index (const char *string, int character)
	Find first occurrence of a character in a string. More...
TRIO_STRING_PUBLIC char *	trio_index_last (const char *string, int character)
	Find last occurrence of a character in a string. More...
TRIO_STRING_PUBLIC int	trio_lower (char *target)
	Convert the alphabetic letters in the string to lower-case. More...
TRIO_STRING_PUBLIC int	trio_match (const char string, const char pattern)
	Compare two strings using wildcards. More...
TRIO_STRING_PUBLIC int	trio_match_case (const char string, const char pattern)
	Compare two strings using wildcards. More...
TRIO_STRING_PUBLIC size_t	trio_span_function (char target, const char source, int(*Function)(int))
	Execute a function on each character in string. More...
TRIO_STRING_PUBLIC char *	trio_substring (const char string, const char substring)
	Search for a substring in a string. More...
TRIO_STRING_PUBLIC char *	trio_substring_max (const char string, size_t max, const char substring)
	Search for a substring in the first `max` characters of a string. More...
TRIO_STRING_PUBLIC char *	trio_tokenize (char string, const char delimiters)
	Tokenize string. More...
TRIO_STRING_PUBLIC trio_long_double_t	trio_to_long_double (const char source, char *endp)
	Convert string to floating-point number. More...
TRIO_STRING_PUBLIC double	trio_to_double (const char source, char *endp)
	Convert string to floating-point number. More...
TRIO_STRING_PUBLIC float	trio_to_float (const char source, char *endp)
	Convert string to floating-point number. More...
TRIO_STRING_PUBLIC long	trio_to_long (const char string, char *endp, int base)
	Convert string to signed integer. More...
TRIO_STRING_PUBLIC unsigned long	trio_to_unsigned_long (const char string, char *endp, int base)
	Convert string to unsigned integer. More...
TRIO_STRING_PUBLIC int	trio_upper (char *target)
	Convert the alphabetic letters in the string to upper-case. More...

Detailed Description

Replacements for the standard C string functions.

SYNOPSIS

cc ... -ltrio -lm

#include <triostr.h>

DESCRIPTION

This package renames, fixes, and extends the standard C string handling functions.

Naming

Renaming is done to provide more clear names, to provide a consistant naming and argument policy, and to hide portability issues.

All functions starts with "trio_".
Target is always the first argument, if present, except where the target is optional, such as trio_to_double.
Functions requiring a size for target includes "_max" in its name, and the size is always the second argument.
Functions performing case-sensitive operations includes "_case" in its name.

Fixing

Fixing is done to avoid subtle error conditions. For example, strncpy does not terminate the result with a zero if the source string is bigger than the maximal length, so technically the result is not a C string anymore. trio_copy_max makes sure that the result is zero terminated.

Extending

Extending is done to provide a richer set of fundamental functions. This includes functionality such as wildcard matching ( trio_match ) and calculation of hash values ( trio_hash ).

Function Documentation

TRIO_STRING_PUBLIC int trio_append ( char * target,

const char * source

)

Append source at the end of target.

Parameters:

target Target string.

source Source string.

Returns:
Boolean value indicating success or failure.
Precondition:
target must point to a memory chunk with sufficient room to contain the target string and source string.
No boundary checking is performed, so insufficient memory will result in a buffer overrun.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC int trio_append_max ( char * target,

size_t max,

const char * source

)

Append at most max characters from source to target.

Parameters:

target Target string.

max Maximum number of characters to append.

source Source string.

Returns:
Boolean value indicating success or failure.
Precondition:
target must point to a memory chuck with sufficient room to contain the target string and the source string (at most max characters).
No boundary checking is performed, so insufficient memory will result in a buffer overrun.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC int trio_contains ( const char * string,

const char * substring

)

Determine if a string contains a substring.

Parameters:

string String to be searched.

substring String to be found.

Returns:
Boolean value indicating success or failure.

TRIO_STRING_PUBLIC int trio_copy ( char * target,

const char * source

)

Copy source to target.

Parameters:

target Target string.

source Source string.

Returns:
Boolean value indicating success or failure.
Precondition:
target must point to a memory chunk with sufficient room to contain the source string.
No boundary checking is performed, so insufficient memory will result in a buffer overrun.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC int trio_copy_max ( char * target,

size_t max,

const char * source

)

Copy at most max characters from source to target.

Parameters:

target Target string.

max Maximum number of characters to append.

source Source string.

Returns:
Boolean value indicating success or failure.
Precondition:
target must point to a memory chunk with sufficient room to contain the source string (at most max characters).
No boundary checking is performed, so insufficient memory will result in a buffer overrun.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC char* trio_create ( size_t size )

Create new string.

Parameters:

size Size of new string.

Returns:
Pointer to string, or NULL if allocation failed.

TRIO_STRING_PUBLIC void trio_destroy ( char * string )

Destroy string.

Parameters:

string String to be freed.

TRIO_STRING_PUBLIC char* trio_duplicate ( const char * source )

Duplicate source.

Parameters:

source Source string.

Returns:
A copy of the source string.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC char* trio_duplicate_max ( const char * source,

size_t max

)

Duplicate at most max characters of source.

Parameters:

source Source string.

max Maximum number of characters to duplicate.

Returns:
A copy of the source string.
Postcondition:
target will be zero terminated.

TRIO_STRING_PUBLIC int trio_equal ( const char * first,

const char * second

)

Compare if two strings are equal.

Parameters:

first First string.

second Second string.

Returns:
Boolean indicating whether the two strings are equal or not.
Case-insensitive comparison.

TRIO_STRING_PUBLIC int trio_equal_case ( const char * first,

const char * second

)

Compare if two strings are equal.

Parameters:

first First string.

second Second string.

Returns:
Boolean indicating whether the two strings are equal or not.
Case-sensitive comparison.

TRIO_STRING_PUBLIC int trio_equal_case_max ( const char * first,

size_t max,

const char * second

)

Compare if two strings up until the first max characters are equal.

Parameters:

first First string.

max Maximum number of characters to compare.

second Second string.

Returns:
Boolean indicating whether the two strings are equal or not.
Case-sensitive comparison.

TRIO_STRING_PUBLIC int trio_equal_locale ( const char * first,

const char * second

)

Compare if two strings are equal.

Parameters:

first First string.

second Second string.

Returns:
Boolean indicating whether the two strings are equal or not.
Collating characters are considered equal.

TRIO_STRING_PUBLIC int trio_equal_max ( const char * first,

size_t max,

const char * second

)

Compare if two strings up until the first max characters are equal.

Parameters:

first First string.

max Maximum number of characters to compare.

second Second string.

Returns:
Boolean indicating whether the two strings are equal or not.
Case-insensitive comparison.

TRIO_STRING_PUBLIC const char* trio_error ( int error_number )

Provide a textual description of an error code (errno).

Parameters:

error_number Error number.

Returns:
Textual description of error_number.

TRIO_STRING_PUBLIC size_t trio_format_date_max ( char * target,

size_t max,

const char * format,

const struct tm * datetime

)

Format the date/time according to format.

Parameters:

target Target string.

max Maximum number of characters to format.

format Formatting string.

datetime Date/time structure.

Returns:
Number of formatted characters.
The formatting string accepts the same specifiers as the standard C function strftime.

TRIO_STRING_PUBLIC unsigned long trio_hash ( const char * string,

int type

)

Calculate a hash value for a string.

Parameters:

string String to be calculated on.

type Hash function.

Returns:
Calculated hash value.
type can be one of the following

TRIO_HASH_PLAIN Plain hash function.

TRIO_STRING_PUBLIC char* trio_index ( const char * string,

int character

)

Find first occurrence of a character in a string.

Parameters:

string String to be searched.

character Character to be found.

A pointer to the found character, or NULL if character was not found.

TRIO_STRING_PUBLIC char* trio_index_last ( const char * string,

int character

)

Find last occurrence of a character in a string.

Parameters:

string String to be searched.

character Character to be found.

A pointer to the found character, or NULL if character was not found.

TRIO_STRING_PUBLIC size_t trio_length ( const char * string )

Count the number of characters in a string.

Parameters:

string String to measure.

Returns:
Number of characters in @string.

TRIO_STRING_PUBLIC int trio_lower ( char * target )

Convert the alphabetic letters in the string to lower-case.

Parameters:

target String to be converted.

Returns:
Number of processed characters (converted or not).

TRIO_STRING_PUBLIC int trio_match ( const char * string,

const char * pattern

)

Compare two strings using wildcards.

Parameters:

string String to be searched.

pattern Pattern, including wildcards, to search for.

Returns:
Boolean value indicating success or failure.
Case-insensitive comparison.
The following wildcards can be used

* Match any number of characters.
? Match a single character.

TRIO_STRING_PUBLIC int trio_match_case ( const char * string,

const char * pattern

)

Compare two strings using wildcards.

Parameters:

string String to be searched.

pattern Pattern, including wildcards, to search for.

Returns:
Boolean value indicating success or failure.
Case-sensitive comparison.
The following wildcards can be used

* Match any number of characters.
? Match a single character.

TRIO_STRING_PUBLIC size_t trio_span_function ( char * target,

const char * source,

int(* Function)(int)

)

Execute a function on each character in string.

Parameters:

target Target string.

source Source string.

Function Function to be executed.

Returns:
Number of processed characters.

TRIO_STRING_PUBLIC char* trio_substring ( const char * string,

const char * substring

)

Search for a substring in a string.

Parameters:

string String to be searched.

substring String to be found.

Returns:
Pointer to first occurrence of substring in string, or NULL if no match was found.

TRIO_STRING_PUBLIC char* trio_substring_max ( const char * string,

size_t max,

const char * substring

)

Search for a substring in the first max characters of a string.

Parameters:

string String to be searched.

max Maximum characters to be searched.

substring String to be found.

Returns:
Pointer to first occurrence of substring in string, or NULL if no match was found.

TRIO_STRING_PUBLIC double trio_to_double ( const char * source,

char ** endp

)

Convert string to floating-point number.

Parameters:

source String to be converted.

endp Pointer to end of the converted string.

Returns:
A floating-point number.
See trio_to_long_double.

TRIO_STRING_PUBLIC float trio_to_float ( const char * source,

char ** endp

)

Convert string to floating-point number.

Parameters:

source String to be converted.

endp Pointer to end of the converted string.

Returns:
A floating-point number.
See trio_to_long_double.

TRIO_STRING_PUBLIC long trio_to_long ( const char * string,

char ** endp,

int base

)

Convert string to signed integer.

Parameters:

string String to be converted.

endp Pointer to end of converted string.

base Radix number of number.

TRIO_STRING_PUBLIC trio_long_double_t trio_to_long_double ( const char * source,

char ** endp

)

Convert string to floating-point number.

Parameters:

source String to be converted.

endp Pointer to end of the converted string.

Returns:
A floating-point number.
The following Extended Backus-Naur form is used
double ::= [ <sign> ] ( <number> | <number> <decimal_point> <number> | <decimal_point> <number> ) [ <exponential> [ <sign> ] <number> ] number ::= 1*( <digit> ) digit ::= ( '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' ) exponential ::= ( 'e' | 'E' ) sign ::= ( '-' | '+' ) decimal_point ::= '.'

TRIO_STRING_PUBLIC unsigned long trio_to_unsigned_long ( const char * string,

char ** endp,

int base

)

Convert string to unsigned integer.

Parameters:

string String to be converted.

endp Pointer to end of converted string.

base Radix number of number.

TRIO_STRING_PUBLIC char* trio_tokenize ( char * string,

const char * delimiters

)

Tokenize string.

Parameters:

string String to be tokenized.

tokens String containing list of delimiting characters.

Returns:
Start of new token.
Warning:
string will be destroyed.

TRIO_STRING_PUBLIC int trio_upper ( char * target )

Convert the alphabetic letters in the string to upper-case.

Parameters:

target The string to be converted.

Returns:
The number of processed characters (converted or not).