String

String manipulation funtions. More...

Data Structures
struct	string_ty
Modules
	String_Accumulator
	String Accumulation functions.
	String_List
	String Lists.
	WString
	Wide char strings.
Defines
#define	str_equal(s1, s2)   ((s1) == (s2))
	test string equality
Typedefs
typedef unsigned long	str_hash_ty
Functions
void	str_release (void)
string_ty *	str_from_c (const char *str)
	make string from C string
string_ty *	str_n_from_c (const char *str, size_t len)
	make string from C string
string_ty *	str_copy (string_ty *str)
	make a copy of a string
void	str_free (string_ty *str)
	release a string
string_ty *	str_catenate (string_ty *str1, string_ty *str2)
	join two strings together
string_ty *	str_cat_three (string_ty *str1, string_ty *str2, string_ty *str3)
	joing strings together
int	str_bool (string_ty *str)
	test a boolean
string_ty *	str_upcase (string_ty *str)
	convert to upper case
string_ty *	str_downcase (string_ty *str)
	convert to lower case
string_ty *	str_capitalize (string_ty *str)
	convert to title case
void	str_dump (void)
	dump the string table
string_ty *	str_field (string_ty *str, int sep, int nth)
	extract a field
void	slow_to_fast (const char *const *, string_ty **, size_t)
	convert tables of strings
string_ty *	str_format (const char *fmt,...)
	format text
string_ty *	str_vformat (const char *fmt, va_list ap)
	format text
int	str_equal (string_ty *str1, string_ty *str2)
	test string equality
string_ty *	str_quote_shell (string_ty *str)
	quote shell meta-characters
string_ty *	str_trim (string_ty *str)
	remove excess white space
string_ty *	str_snip (string_ty *str)
	remove leading and trailing white space
int	str_validate (const string_ty *str)
	check is valid
int	str_leading_prefix (string_ty *haystack, string_ty *needle)
	look for a leading prefix
int	str_trailing_suffix (string_ty *haystack, string_ty *needle)
	look for a trailing suffix
string_ty *	str_identifier (string_ty *str)
string_ty *	str_replace (string_ty *str, string_ty *lhs, string_ty *rhs, int maximum=-1)

---

Detailed Description

String manipulation funtions.

---

Define Documentation

#define str_equal	(		s1,
			s2
	)		((s1) == (s2))

test string equality

See also:

str_equal()

The str_equal macro is used to accellerate string equality tests. Users shall always write code as if they did not know that a string equality test is a pointer equality test.

Definition at line 399 of file str.h.

---

Typedef Documentation

typedef unsigned long str_hash_ty

Definition at line 31 of file str.h.

---

Function Documentation

void slow_to_fast	(	const char *const *	,
		string_ty **	,
		size_t
	)

convert tables of strings

The slow_to_fast function is used to convert tables for normal C strings into tables of reference countest strings. Use amlost exclusively by the fmtgen-generated sources.

Returns:

void

int str_bool

(

string_ty *

str

)

test a boolean

The str_bool function is used to test the value of a string, as if it contained a number. If it doesn't contain a number, it is as if the strings was "1".

Parameters:

str	The string to be tested. Will not be modified.

Returns:

Zero if the numeric value in the strings was zero, or the empty string. One if the numeric value in the string was non-zero, or the string was non-numeric.

string_ty* str_capitalize

(

string_ty *

str

)

convert to title case

The str_capitalize function is used to create a new string where the first letter or each word of the inopuyt string are upper case, and the remaining letters in each word are lower case. (Sometimes called Title Case.)

Parameters:

str	The string to be converted. Will not be modified (the operation is not performed in situ).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_cat_three	(	string_ty *	str1,
		string_ty *	str2,
		string_ty *	str3
	)

joing strings together

The str_cat_three function is used to join three strings together to form a new string. The are joined in the order given.

Parameters:

str1	A string to be joined. Will not be modified.
str2	A string to be joined. Will not be modified.
str3	A string to be joined. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_catenate	(	string_ty *	str1,
		string_ty *	str2
	)

join two strings together

The str_catenate function is used to join two strings togther to form a new string. The are joined in the order given.

Parameters:

str1	A string to be joined. Will not be modified.
str2	A string to be joined. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_copy

(

string_ty *

str

)

make a copy of a string

The str_copy function is used to make a copy of a string.

Parameters:

str	The string to be copied. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_downcase

(

string_ty *

str

)

convert to lower case

The str_downcase function is used to create a new string where the upper case characters in the input string are converted to lower case.

Parameters:

str	The string to be converted. Will not be modified (the operation is not performed in situ).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

void str_dump

(

void

)

dump the string table

The str_dum function is used to dump the contents of the string table to the standard error. Only useful for debugging.

Returns:

void

int str_equal	(	string_ty *	str1,
		string_ty *	str2
	)

test string equality

The str_equal function is used to test to see if two strings are exactly the same.

Parameters:

str1	A string to be compared. Will not be modified.
str2	A string to be compared. Will not be modified.

Note:

Users shall always write code as if they did not know that a string equality test is a pointer equality test.

Returns:

Non-zero if the strings are equal, zero if the strings are unequal.

string_ty* str_field	(	string_ty *	str,
		int	sep,
		int	nth
	)

extract a field

The str_field function is used to extract the nth field, where each field is separated by the sep string.

Parameters:

str	The string from which the field is to be extracted. Will not be modified (the operation not performed in situ).
sep	The string which separates each field.
nth	The number of the field to be extracted. Zero based. If too high, the emtry string is returned.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_format	(	const char *	fmt,
			...
	)

format text

The str_format function is used to create a new string by interpreting the fmt string. All formats understood by the ANSI C printf(3) are understodd by this function (but probably not your favorite proprietary extension). In addition the 'S' specifier expects a string_ty * argument.

Parameters:

fmt	The format string to be interpreted when constructing the return value.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

void str_free

(

string_ty *

str

)

release a string

The str_free function is used to indicate that a string hash been finished with. This is the only way to release strings. Do not use the free() function.

Parameters:

str	The string to be freed.

Returns:

void

string_ty* str_from_c

(

const char *

str

)

make string from C string

The str_from_c function is used to make a string from a null terminated C string.

Parameters:

str	The C string to be copied. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_identifier

(

string_ty *

str

)

The str_identifier function is used to generate another string, replaceing all non-C-identifier characters with underscore. The intention is to generate a valid C identifier from the string.

Parameters:

str	The string to be converted.

int str_leading_prefix	(	string_ty *	haystack,
		string_ty *	needle
	)

look for a leading prefix

The str_leading_prefix function is used to test whether the needle argument is a leading prefix of the haystack argument.

Parameters:

haystack	The large string which allegedly contains the needle.
needle	The substring to be tested for.

Returns:

Non-zero if is a leading prefix, zero if not.

string_ty* str_n_from_c	(	const char *	str,
		size_t	len
	)

make string from C string

The str_n_from_c function is used to make a string from an array of characters. No null terminator is assumed.

Parameters:

str	The C string to be copied. Will not be modified.
len	The maximum number of characters to be used (fewer will be used if there is an included NUL).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_quote_shell

(

string_ty *

str

)

quote shell meta-characters

The str_quote_shell function is used to create a new string which quotes the shell meta-characters in the input string.

Parameters:

str	The string to be converted. Will not be modified (the operation is not performed in situ).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

void str_release

(

void

)

string_ty* str_replace	(	string_ty *	str,
		string_ty *	lhs,
		string_ty *	rhs,
		int	maximum = -1
	)

The str_replace function may be used to alter a string by replacing one constant substring with another.

Note:

The replacement is not done in situ. The original str is unaltered.

Parameters:

str	The string to be altered.
lhs	The substring to look for within str
rhs	The substring to replace lhs if found within str
maximum	The maximum number of times to perform the replacement. Defaults to "infinity".

Returns:

A new string with the replacements made.

string_ty* str_snip

(

string_ty *

str

)

remove leading and trailing white space

The str_snip function is used to remove white space from the beginning and end of the string. Interior white space is unchanged.

Parameters:

str	The string to be converted.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with.

int str_trailing_suffix	(	string_ty *	haystack,
		string_ty *	needle
	)

look for a trailing suffix

The str_trailing_suffix function is used to test whether the needle argument is a trailing suffix of the haystack argument.

Parameters:

haystack	The large string which allegedly contains the needle.
needle	The substring to be tested for.

Returns:

Non-zero if is a trailing suffix, zero if not.

string_ty* str_trim

(

string_ty *

str

)

remove excess white space

The str_trim function is used to remove white space from the beginning and end of the string, and replace all other runs of one or more white space characters with a single space.

Parameters:

str	The string to be converted. Will not be modified (the operation is not performed in situ).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

string_ty* str_upcase

(

string_ty *

str

)

convert to upper case

The str_upcase function is used to create a new string where the lower case characters in the input string are converted to upper case.

Parameters:

str	The string to be converted. Will not be modified (the operation is not performed in situ).

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

int str_validate

(

const string_ty *

str

)

check is valid

The str_validate function is used to confirm that the given string pointer, str, points to a valid string. Usually used for debugging, often in assert()s.

Parameters:

str	The string to be validated. Willnot be modified.

Returns:

Non-zero if valid, zero if invalid.

string_ty* str_vformat	(	const char *	fmt,
		va_list	ap
	)

format text

The str_vformat function is used to create a new string by interpreting the fmt string. All formats understood by the ANSI C printf(3) are understodd by this function (but probably not your favorite proprietary extension). In addition the 'S' specifier expects a string_ty * argument.

Parameters:

fmt	The format string to be interpreted when constructing the return value.
ap	Where to obtain additional arguments required by the fmt string.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.