Functions
Static String Functions.

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

Functions

TRIO_PUBLIC_STRING char * trio_create (size_t size)
 Create new string. More...
 
TRIO_PUBLIC_STRING void trio_destroy (char *string)
 Destroy string. More...
 
TRIO_PUBLIC_STRING size_t trio_length (const char *string)
 Count the number of characters in a string. More...
 
TRIO_PUBLIC_STRING size_t trio_length_max (const char *string, size_t max)
 Count at most max characters in a string. More...
 
TRIO_PUBLIC_STRING int trio_append (char *target, const char *source)
 Append source at the end of target. More...
 
TRIO_PUBLIC_STRING int trio_append_max (char *target, size_t max, const char *source)
 Append at most max characters from source to target. More...
 
TRIO_PUBLIC_STRING int trio_contains (const char *string, const char *substring)
 Determine if a string contains a substring. More...
 
TRIO_PUBLIC_STRING int trio_copy (char *target, const char *source)
 Copy source to target. More...
 
TRIO_PUBLIC_STRING int trio_copy_max (char *target, size_t max, const char *source)
 Copy at most max - 1 characters from source to target. More...
 
TRIO_PUBLIC_STRING char * trio_duplicate (const char *source)
 Duplicate source. More...
 
TRIO_PUBLIC_STRING char * trio_duplicate_max (const char *source, size_t max)
 Duplicate at most max characters of source. More...
 
TRIO_PUBLIC_STRING int trio_equal (const char *first, const char *second)
 Compare if two strings are equal. More...
 
TRIO_PUBLIC_STRING int trio_equal_case (const char *first, const char *second)
 Compare if two strings are equal. More...
 
TRIO_PUBLIC_STRING 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_PUBLIC_STRING int trio_equal_locale (const char *first, const char *second)
 Compare if two strings are equal. More...
 
TRIO_PUBLIC_STRING 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_PUBLIC_STRING const char * trio_error (int error_number)
 Provide a textual description of an error code (errno). More...
 
TRIO_PUBLIC_STRING 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_PUBLIC_STRING unsigned long trio_hash (const char *string, int type)
 Calculate a hash value for a string. More...
 
TRIO_PUBLIC_STRING char * trio_index (const char *string, int character)
 Find first occurrence of a character in a string. More...
 
TRIO_PUBLIC_STRING char * trio_index_last (const char *string, int character)
 Find last occurrence of a character in a string. More...
 
TRIO_PUBLIC_STRING int trio_lower (char *target)
 Convert the alphabetic letters in the string to lower-case. More...
 
TRIO_PUBLIC_STRING int trio_match (const char *string, const char *pattern)
 Compare two strings using wildcards. More...
 
TRIO_PUBLIC_STRING int trio_match_case (const char *string, const char *pattern)
 Compare two strings using wildcards. More...
 
TRIO_PUBLIC_STRING size_t trio_span_function (char *target, const char *source, int(*Function)(int))
 Execute a function on each character in string. More...
 
TRIO_PUBLIC_STRING char * trio_substring (const char *string, const char *substring)
 Search for a substring in a string. More...
 
TRIO_PUBLIC_STRING 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_PUBLIC_STRING char * trio_tokenize (char *string, const char *delimiters)
 Tokenize string. More...
 
TRIO_PUBLIC_STRING trio_long_double_t trio_to_long_double (const char *source, char **endp)
 Convert string to floating-point number. More...
 
TRIO_PUBLIC_STRING double trio_to_double (const char *source, char **endp)
 Convert string to floating-point number. More...
 
TRIO_PUBLIC_STRING float trio_to_float (const char *source, char **endp)
 Convert string to floating-point number. More...
 
TRIO_PUBLIC_STRING long trio_to_long (const char *string, char **endp, int base)
 Convert string to signed integer. More...
 
TRIO_PUBLIC_STRING int trio_to_lower (int source)
 Convert one alphabetic letter to lower-case. More...
 
TRIO_PUBLIC_STRING unsigned long trio_to_unsigned_long (const char *string, char **endp, int base)
 Convert string to unsigned integer. More...
 
TRIO_PUBLIC_STRING int trio_to_upper (int source)
 Convert one alphabetic letter to upper-case. More...
 
TRIO_PUBLIC_STRING 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.

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_append()

TRIO_PUBLIC_STRING int trio_append ( char *  target,
const char *  source 
)

Append source at the end of target.

Parameters
targetTarget string.
sourceSource 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.

References trio_append_max().

Referenced by trio_length_max().

◆ trio_append_max()

TRIO_PUBLIC_STRING int trio_append_max ( char *  target,
size_t  max,
const char *  source 
)

Append at most max characters from source to target.

Parameters
targetTarget string.
maxMaximum number of characters to append.
sourceSource 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.

References trio_contains(), and trio_length().

Referenced by trio_append().

◆ trio_contains()

TRIO_PUBLIC_STRING int trio_contains ( const char *  string,
const char *  substring 
)

Determine if a string contains a substring.

Parameters
stringString to be searched.
substringString to be found.
Returns
Boolean value indicating success or failure.

References trio_copy().

Referenced by trio_append_max(), and trio_string_contains().

◆ trio_copy()

TRIO_PUBLIC_STRING int trio_copy ( char *  target,
const char *  source 
)

Copy source to target.

Parameters
targetTarget string.
sourceSource 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.

References trio_copy_max().

Referenced by trio_contains().

◆ trio_copy_max()

TRIO_PUBLIC_STRING int trio_copy_max ( char *  target,
size_t  max,
const char *  source 
)

Copy at most max - 1 characters from source to target.

Parameters
targetTarget string.
maxMaximum number of characters to append (one of which is a NUL terminator). In other words source must point to at least max - 1 bytes, but target must point to at least max bytes.
sourceSource string.
Returns
Boolean value indicating success or failure.
Precondition
target must point to a memory chunk with sufficient room to contain the source string and a NUL terminator (at most max bytes total).
No boundary checking is performed, so insufficient memory will result in a buffer overrun.
Postcondition
target will be zero terminated.

References trio_duplicate().

Referenced by trio_copy().

◆ trio_create()

TRIO_PUBLIC_STRING char* trio_create ( size_t  size)

Create new string.

Parameters
sizeSize of new string.
Returns
Pointer to string, or NULL if allocation failed.

References trio_destroy().

◆ trio_destroy()

TRIO_PUBLIC_STRING void trio_destroy ( char *  string)

Destroy string.

Parameters
stringString to be freed.

References trio_length().

Referenced by trio_create(), trio_string_destroy(), trio_unregister(), and trio_xstring_set().

◆ trio_duplicate()

TRIO_PUBLIC_STRING char* trio_duplicate ( const char *  source)

Duplicate source.

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

Referenced by trio_copy_max(), trio_register(), and trio_xstring_set().

◆ trio_duplicate_max()

TRIO_PUBLIC_STRING char* trio_duplicate_max ( const char *  source,
size_t  max 
)

Duplicate at most max characters of source.

Parameters
sourceSource string.
maxMaximum number of characters to duplicate.
Returns
A copy of the source string.
Postcondition
target will be zero terminated.

References trio_length().

◆ trio_equal()

TRIO_PUBLIC_STRING int trio_equal ( const char *  first,
const char *  second 
)

Compare if two strings are equal.

Parameters
firstFirst string.
secondSecond string.
Returns
Boolean indicating whether the two strings are equal or not.

Case-insensitive comparison.

Referenced by trio_equal_locale(), and trio_register().

◆ trio_equal_case()

TRIO_PUBLIC_STRING int trio_equal_case ( const char *  first,
const char *  second 
)

Compare if two strings are equal.

Parameters
firstFirst string.
secondSecond string.
Returns
Boolean indicating whether the two strings are equal or not.

Case-sensitive comparison.

References trio_equal_case_max().

◆ trio_equal_case_max()

TRIO_PUBLIC_STRING 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
firstFirst string.
maxMaximum number of characters to compare.
secondSecond string.
Returns
Boolean indicating whether the two strings are equal or not.

Case-sensitive comparison.

References trio_equal_locale().

Referenced by trio_equal_case().

◆ trio_equal_locale()

TRIO_PUBLIC_STRING int trio_equal_locale ( const char *  first,
const char *  second 
)

Compare if two strings are equal.

Parameters
firstFirst string.
secondSecond string.
Returns
Boolean indicating whether the two strings are equal or not.

Collating characters are considered equal.

References trio_equal(), and trio_equal_max().

Referenced by trio_equal_case_max().

◆ trio_equal_max()

TRIO_PUBLIC_STRING 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
firstFirst string.
maxMaximum number of characters to compare.
secondSecond string.
Returns
Boolean indicating whether the two strings are equal or not.

Case-insensitive comparison.

Referenced by trio_equal_locale(), and trio_substring_max().

◆ trio_error()

TRIO_PUBLIC_STRING const char* trio_error ( int  error_number)

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

Parameters
error_numberError number.
Returns
Textual description of error_number.

References trio_format_date_max().

◆ trio_format_date_max()

TRIO_PUBLIC_STRING 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
targetTarget string.
maxMaximum number of characters to format.
formatFormatting string.
datetimeDate/time structure.
Returns
Number of formatted characters.

The formatting string accepts the same specifiers as the standard C function strftime.

References trio_hash().

Referenced by trio_error().

◆ trio_hash()

TRIO_PUBLIC_STRING unsigned long trio_hash ( const char *  string,
int  type 
)

Calculate a hash value for a string.

Parameters
stringString to be calculated on.
typeHash function.
Returns
Calculated hash value.

type can be one of the following

  • TRIO_HASH_PLAIN Plain hash function.

References trio_index().

Referenced by trio_format_date_max().

◆ trio_index()

TRIO_PUBLIC_STRING char* trio_index ( const char *  string,
int  character 
)

Find first occurrence of a character in a string.

Parameters
stringString to be searched.
characterCharacter to be found.
Returns
A pointer to the found character, or NULL if character was not found.

References trio_index_last().

Referenced by trio_hash().

◆ trio_index_last()

TRIO_PUBLIC_STRING char* trio_index_last ( const char *  string,
int  character 
)

Find last occurrence of a character in a string.

Parameters
stringString to be searched.
characterCharacter to be found.
Returns
A pointer to the found character, or NULL if character was not found.

References trio_lower().

Referenced by trio_index().

◆ trio_length()

TRIO_PUBLIC_STRING size_t trio_length ( const char *  string)

Count the number of characters in a string.

Parameters
stringString to measure.
Returns
Number of characters in string.

References trio_length_max().

Referenced by trio_append_max(), trio_destroy(), trio_duplicate_max(), trio_register(), and trio_substring_max().

◆ trio_length_max()

TRIO_PUBLIC_STRING size_t trio_length_max ( const char *  string,
size_t  max 
)

Count at most max characters in a string.

Parameters
stringString to measure.
maxMaximum number of characters to count.
Returns
The maximum value of max and number of characters in string.

References trio_append().

Referenced by trio_length().

◆ trio_lower()

TRIO_PUBLIC_STRING int trio_lower ( char *  target)

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

Parameters
targetString to be converted.
Returns
Number of processed characters (converted or not).

References trio_match(), trio_span_function(), and trio_to_lower().

Referenced by trio_index_last().

◆ trio_match()

TRIO_PUBLIC_STRING int trio_match ( const char *  string,
const char *  pattern 
)

Compare two strings using wildcards.

Parameters
stringString to be searched.
patternPattern, 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.

Referenced by trio_lower().

◆ trio_match_case()

TRIO_PUBLIC_STRING int trio_match_case ( const char *  string,
const char *  pattern 
)

Compare two strings using wildcards.

Parameters
stringString to be searched.
patternPattern, 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.

References trio_span_function().

◆ trio_span_function()

TRIO_PUBLIC_STRING size_t trio_span_function ( char *  target,
const char *  source,
int(*)(int)  Function 
)

Execute a function on each character in string.

Parameters
targetTarget string.
sourceSource string.
FunctionFunction to be executed.
Returns
Number of processed characters.

References trio_substring().

Referenced by trio_lower(), trio_match_case(), and trio_upper().

◆ trio_substring()

TRIO_PUBLIC_STRING char* trio_substring ( const char *  string,
const char *  substring 
)

Search for a substring in a string.

Parameters
stringString to be searched.
substringString to be found.
Returns
Pointer to first occurrence of substring in string, or NULL if no match was found.

References trio_substring_max().

Referenced by trio_span_function().

◆ trio_substring_max()

TRIO_PUBLIC_STRING 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
stringString to be searched.
maxMaximum characters to be searched.
substringString to be found.
Returns
Pointer to first occurrence of substring in string, or NULL if no match was found.

References trio_equal_max(), trio_length(), and trio_tokenize().

Referenced by trio_substring().

◆ trio_to_double()

TRIO_PUBLIC_STRING double trio_to_double ( const char *  source,
char **  endp 
)

Convert string to floating-point number.

Parameters
sourceString to be converted.
endpPointer to end of the converted string.
Returns
A floating-point number.

See trio_to_long_double.

References trio_to_float(), and trio_to_long_double().

◆ trio_to_float()

TRIO_PUBLIC_STRING float trio_to_float ( const char *  source,
char **  endp 
)

Convert string to floating-point number.

Parameters
sourceString to be converted.
endpPointer to end of the converted string.
Returns
A floating-point number.

See trio_to_long_double.

References trio_to_long(), and trio_to_long_double().

Referenced by trio_to_double().

◆ trio_to_long()

TRIO_PUBLIC_STRING long trio_to_long ( const char *  string,
char **  endp,
int  base 
)

Convert string to signed integer.

Parameters
stringString to be converted.
endpPointer to end of converted string.
baseRadix number of number.

References trio_to_lower().

Referenced by trio_to_float().

◆ trio_to_long_double()

TRIO_PUBLIC_STRING trio_long_double_t trio_to_long_double ( const char *  source,
char **  endp 
)

Convert string to floating-point number.

Parameters
sourceString to be converted.
endpPointer 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 ::= '.'

Referenced by trio_to_double(), trio_to_float(), and trio_tokenize().

◆ trio_to_lower()

TRIO_PUBLIC_STRING int trio_to_lower ( int  source)

Convert one alphabetic letter to lower-case.

Parameters
sourceThe letter to be converted.
Returns
The converted letter.

References trio_to_unsigned_long().

Referenced by trio_lower(), and trio_to_long().

◆ trio_to_unsigned_long()

TRIO_PUBLIC_STRING unsigned long trio_to_unsigned_long ( const char *  string,
char **  endp,
int  base 
)

Convert string to unsigned integer.

Parameters
stringString to be converted.
endpPointer to end of converted string.
baseRadix number of number.

References trio_to_upper().

Referenced by trio_to_lower().

◆ trio_to_upper()

TRIO_PUBLIC_STRING int trio_to_upper ( int  source)

Convert one alphabetic letter to upper-case.

Parameters
sourceThe letter to be converted.
Returns
The converted letter.

Referenced by trio_to_unsigned_long().

◆ trio_tokenize()

TRIO_PUBLIC_STRING char* trio_tokenize ( char *  string,
const char *  delimiters 
)

Tokenize string.

Parameters
stringString to be tokenized.
delimitersString containing list of delimiting characters.
Returns
Start of new token.
Warning
string will be destroyed.

References trio_to_long_double().

Referenced by trio_substring_max().

◆ trio_upper()

TRIO_PUBLIC_STRING int trio_upper ( char *  target)

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

Parameters
targetThe string to be converted.
Returns
The number of processed characters (converted or not).

References trio_span_function().