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.

- 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_PUBLIC_STRING 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_PUBLIC_STRING 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.

References trio_length().

TRIO_PUBLIC_STRING 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.

Referenced by trio_string_contains().

TRIO_PUBLIC_STRING 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.

Referenced by trio_string_append().

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

  target | Target string.
  max | Maximum 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.
  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 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.

TRIO_PUBLIC_STRING 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_PUBLIC_STRING void trio_destroy | ( | char * | string) |  |

Destroy string.

Parameters

  string | String to be freed.

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

TRIO_PUBLIC_STRING 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.

References trio_length().

Referenced by trio_register(), and trio_xstring_set().

TRIO_PUBLIC_STRING 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.

References trio_length().

TRIO_PUBLIC_STRING 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.

Referenced by trio_equal_locale(), and trio_register().

TRIO_PUBLIC_STRING 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_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

  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_PUBLIC_STRING 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.

References trio_equal().

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

  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.

Referenced by trio_substring_max().

TRIO_PUBLIC_STRING 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_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

  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_PUBLIC_STRING 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_PUBLIC_STRING 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.

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

TRIO_PUBLIC_STRING 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.

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

TRIO_PUBLIC_STRING 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`.

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

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

Count at most `max` characters in a string.

Parameters

  string | String to measure.
  max | Maximum number of characters to count.

Returns
  The maximum value of `max` and number of characters in `string`.

TRIO_PUBLIC_STRING 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).

References trio_span_function(), and trio_to_lower().

TRIO_PUBLIC_STRING 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_PUBLIC_STRING 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_PUBLIC_STRING size_t trio_span_function | ( | char * | target,
|  | const char * | source,
|  | int(*)(int) | Function
| ) |  |

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.

Referenced by trio_lower(), and trio_upper().

TRIO_PUBLIC_STRING 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_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

  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.

References trio_equal_max(), and trio_length().

TRIO_PUBLIC_STRING 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.

References trio_to_long_double().

TRIO_PUBLIC_STRING 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.

References trio_to_long_double().

TRIO_PUBLIC_STRING 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_PUBLIC_STRING 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 ::= '.'

Referenced by trio_to_double(), and trio_to_float().

TRIO_PUBLIC_STRING int trio_to_lower | ( | int | source) |  |

Convert one alphabetic letter to lower-case.

Parameters

  source | The letter to be converted.

Returns
  The converted letter.

Referenced by trio_lower().

TRIO_PUBLIC_STRING 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_PUBLIC_STRING int trio_to_upper | ( | int | source) |  |

Convert one alphabetic letter to upper-case.

Parameters

  source | The letter to be converted.

Returns
  The converted letter.

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

Tokenize string.

Parameters

  string | String to be tokenized.
  delimiters | String containing list of delimiting characters.

Returns
  Start of new token.

Warning
  `string` will be destroyed.

TRIO_PUBLIC_STRING 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).

References trio_span_function().

Copyright (C) 2001 - 2006 Bjørn Reese and Daniel Stenberg.