string
["Little Useful Bits" Library]

This utility provides some simple string manipulation functions which augment those found in the standard ANSI-C library. More...

Functions
char *	lub_string_dup (const char *string)
void	lub_string_cat (char **string_ptr, const char *text)
void	lub_string_catn (char **string_ptr, const char *text, size_t length)
char *	lub_string_dupn (const char *string, unsigned length)
const char *	lub_string_suffix (const char *string)
int	lub_string_nocasecmp (const char *cs, const char *ct)
const char *	lub_string_nocasestr (const char *cs, const char *ct)
void	lub_string_free (char *string)

---

Detailed Description

This utility provides some simple string manipulation functions which augment those found in the standard ANSI-C library.

As a rule of thumb if a function returns "char *" then the calling client becomes responsible for invoking lub_string_free() to release the dynamically allocated memory.

If a "const char *" is returned then the client has no responsiblity for releasing memory.

---

Function Documentation

void lub_string_cat	(	char **	string_ptr,
		const char *	text
	)

This operation concatinates the specified text onto an existing string.

Precondition:

• 'string_ptr' must contain reference to NULL or to a dynamically allocated string.

Postcondition:

• The old string referenced by 'string_ptr' will be automatically released
• 'string_ptr' will be updated to point to a dynamically allocated string containing the concatinated text.
• If there is insufficient resource to extend the string then it will not be extended.
• The client maintains responsibility for releasing the string reference by string_ptr when they are finished using it.

Parameters:

string_ptr	A pointer to the string to concatinate
text	The text to be appended

void lub_string_catn	(	char **	string_ptr,
		const char *	text,
		size_t	length
	)

This operation concatinates a specified length of some text onto an existing string.

Precondition:

• 'string_ptr' must contain reference to NULL or to a dynamically allocated string.

Postcondition:

• The old string referenced by 'string_ptr' will be automatically released.
• 'string_ptr' will be updated to point to a dynamically allocated string containing the concatinated text.
• If there is insufficient resource to extend the string then it will not be extended.
• If there length passed in is greater than that of the specified 'text' then the length of the 'text' will be assumed.
• The client maintains responsibility for releasing the string reference by string_ptr when they are finished using it.

Parameters:

string_ptr	A pointer to the string to concatinate
text	The text to be appended
length	The length of text to be appended

char* lub_string_dup

(

const char *

string

)

This operation duplicates the specified string.

Precondition:

• none

Returns:

A dynamically allocated string containing the same content as that specified.

Postcondition:

• The client is responsible for calling lub_string_free() with the returned string when they are finished using it.

Parameters:

string

The string to duplicate

char* lub_string_dupn	(	const char *	string,
		unsigned	length
	)

This operation dupicates a specified length of some text into a new string.

Precondition:

• none

Returns:

A dynamically allocated string containing the same content as that specified.

Postcondition:

• The client is responsible for calling lub_string_free() with the returned string when they are finished using it.

Parameters:

string	The string containing the text to duplicate
length	The length of text to be duplicated

void lub_string_free

(

char *

string

)

This operation releases the resources associated with a dynamically allocated string.

Precondition:

• The calling client must have responsibility for the passed string.

Returns:

none

Postcondition:

• The string is no longer usable, any references to it must be discarded.

Parameters:

string

The string to be released

int lub_string_nocasecmp	(	const char *	cs,
		const char *	ct
	)

This operation compares string cs to string ct in a case insensitive manner.

Precondition:

• none

Returns:

• < 0 if cs < ct
• 0 if cs == ct
• > 0 if cs > ct

Postcondition:

• none

Parameters:

cs	The first string for the comparison
ct	The second string for the comparison

const char* lub_string_nocasestr	(	const char *	cs,
		const char *	ct
	)

This operation performs a case insensitive search for a substring within another string.

Precondition:

• none

Returns:

pointer to first occurance of a case insensitive version of the string ct, or NULL if not present.

Postcondition:

• none

Parameters:

cs	The string within which to find a substring
ct	The substring for which to search

const char* lub_string_suffix

(

const char *

string

)

This operation returns a pointer to the last (space separated) word in the specified string.

Precondition:

• none

Returns:

A pointer to the last word in the string.

Postcondition:

• none

Parameters:

string

The string from which to extract a suffix

---