From 13c27199231cbc2cc83969ada741b95be1cca4d3 Mon Sep 17 00:00:00 2001 From: Matthias Andree Date: Wed, 10 Nov 2004 19:04:29 +0000 Subject: Import Trio 1.10 into fetchmail's trunk. svn path=/trunk/; revision=3995 --- trio/html/group___static_strings.html | 1809 +++++++++++++++++++++++++++++++++ 1 file changed, 1809 insertions(+) create mode 100644 trio/html/group___static_strings.html (limited to 'trio/html/group___static_strings.html') diff --git a/trio/html/group___static_strings.html b/trio/html/group___static_strings.html new file mode 100644 index 00000000..840f36a5 --- /dev/null +++ b/trio/html/group___static_strings.html @@ -0,0 +1,1809 @@ + + + + + TRIO + + + + + +Main Page Modules +

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

+