Main Page Modules

# Static String Functions.

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

## Functions

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

## 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 Static String Functions..
- 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. Static String Functions. 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.

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.

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.

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

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.

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.

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.

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.

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.

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

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

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(* | 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_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.

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 Static String Functions..

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 Static String Functions..

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

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.

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

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