strlib.h

This interface defines a general library for dynamically allocated strings. The major differences between traditional C strings and those defined using this interface are:

The strlib.h interface takes care of memory allocation, ensuring that there is sufficient space to hold the result of each string operation.
Clients of the strlib.h interface are expected to treat all strings as immutable and refrain from writing into the character array.

Functions
concat(s1, s2)	Concatenates two strings by joining them end to end.
charAt(s, i)	Returns the character at position `i` in the string `s`.
substring(s, p1, p2)	Returns a copy of the substring of `s` consisting of the characters between index positions `p1` and `p2`, inclusive.
charToString(ch)	Takes a single character and returns a one-character string consisting of that character.
stringLength(s)	Returns the length of the string `s`.
copyString(s)	Copies the string `s` into dynamically allocated storage and returns the new string.
stringEqual(s1, s2)	Returns `true` if the strings `s1` and `s2` are equal.
stringEqualIgnoreCase(s1, s2)	Returns `true` if the strings `s1` and `s2` are equal, ignoring differences in case.
stringCompare(s1, s2)	Returns -1 if string `s1` comes before `s2` in lexicographic order, 0 if they are equal, and +1 if `s1` comes after `s2`.
startsWith(s1, s2)	Returns `true` if `s1` starts with `s2`.
endsWith(s1, s2)	Returns `true` if `s1` ends with `s2`.
findChar(ch, text, start)	Searches for the character `ch` beginning at position `start` in the string `text` and returns the first index at which it appears or -1 if no match is found.
findString(str, text, start)	Searches for the string `str` beginning at position `start` in the string `text` and returns the first index at which it appears or -1 if no match is found.
findLastChar(ch, text)	Returns the last index of `ch` in `text`, or -1 if the search value does not appear.
findLastString(str, text)	Returns the last index of `str` in `text`, or -1 if the search value does not appear.
toLowerCase(s)	Returns a new string with all alphabetic characters converted to lowercase.
toUpperCase(s)	Returns a new string with all alphabetic characters converted to uppercase.
integerToString(n)	Converts an integer into the corresponding string of digits.
stringToInteger(s)	Converts a string of digits into an integer.
realToString(d)	Converts a floating-point number into the corresponding string form.
stringToReal(s)	Converts a string representing a real number into its corresponding value.
trim(str)	Returns a new string after removing any whitespace characters from the beginning and end of the argument.
quoteString(str)	Returns a quoted string that can be read by the C parser.
quoteHTML(str)	Returns a string that appears correctly in HTML by changing HTML special characters to character entities.
stringArrayLength(array)	Returns the length of a `NULL`-terminated string array.
searchStringArray(str, array)	Finds a string in a `NULL`-terminated string array and returns the first index at which the string appears, or -1 if it is not found.

Function detail

string concat(string s1, string s2);

Concatenates two strings by joining them end to end. For example, concat("ABC", "DE") returns the string "ABCDE".

Usage:

s = concat(s1, s2);

char charAt(string s, int i);

Returns the character at position i in the string s. This function is included in the library to make the type string a true abstract type in the sense that all of the necessary operations can be invoked using functions. Calling charAt(s, i) is like selecting s[i], except that charAt checks to see if i is within the range of legal index positions, which extend from 0 to stringLength(s). Calling charAt(s, stringLength(s))Usage:

ch = charAt(s, i);

string substring(string s, int p1, int p2);

Returns a copy of the substring of s consisting of the characters between index positions p1 and p2, inclusive. The following special cases apply:

If p1 is less than 0, it is assumed to be 0.
If p2 is greater than or equal to the length of the string, p2 is set to stringLength(s) - 1.
If p2 < p1, substring returns the empty string.

Usage:

t = substring(s, p1, p2);

string charToString(char ch);

Takes a single character and returns a one-character string consisting of that character. The charToString function is useful, for example, if you need to concatenate a string and a character. Since concat requires two strings, you must first convert the character into a string.

Usage:

s = charToString(ch);

int stringLength(string s);

Returns the length of the string s.

Usage:

len = stringLength(s);

string copyString(string s);

Copies the string s into dynamically allocated storage and returns the new string. This function is not ordinarily required when this package is used on its own but is often necessary when you are working with more than one string package.

Usage:

newstr = copyString(s);

bool stringEqual(string s1, string s2);

Returns true if the strings s1 and s2 are equal. For the strings to be considered equal, every character in one string must precisely match the corresponding character in the other. Uppercase and lowercase characters are considered to be different.

Usage:

if (stringEqual(s1, s2)) ...

bool stringEqualIgnoreCase(string s1, string s2);

Returns true if the strings s1 and s2 are equal, ignoring differences in case.

Usage:

if (stringEqualIgnoreCase(s1, s2)) ...

int stringCompare(string s1, string s2);

Returns -1 if string s1 comes before s2 in lexicographic order, 0 if they are equal, and +1 if s1 comes after s2.

Usage:

if (stringCompare(s1, s2) < 0) ...

bool startsWith(string s1, string s2);

Returns true if s1 starts with s2.

Usage:

if (startsWith(s1, s2)) ...

bool endsWith(string s1, string s2);

Returns true if s1 ends with s2.

Usage:

if (endsWith(s1, s2)) ...

int findChar(char ch, string text, int start);

Searches for the character ch beginning at position start in the string text and returns the first index at which it appears or -1 if no match is found.

Usage:

p = findChar(ch, text, start);

int findString(string str, string text, int start);

Searches for the string str beginning at position start in the string text and returns the first index at which it appears or -1 if no match is found.

Usage:

p = findString(str, text, start);

int findLastChar(char ch, string text);

Returns the last index of ch in text, or -1 if the search value does not appear.

Usage:

p = findLastChar(ch, text);

int findLastString(string str, string text);

Returns the last index of str in text, or -1 if the search value does not appear.

Usage:

p = findLastString(str, text);

string toLowerCase(string s);

Returns a new string with all alphabetic characters converted to lowercase.

Usage:

s = toLowerCase(s);

string toUpperCase(string s);

Returns a new string with all alphabetic characters converted to uppercase.

Usage:

s = toUpperCase(s);

string integerToString(int n);

Converts an integer into the corresponding string of digits. For example, integerToString(123) returns "123" as a string.

Usage:

s = integerToString(n);

int stringToInteger(string s);

Converts a string of digits into an integer. If the string is not a legal integer or contains extraneous characters, stringToInteger signals an error condition.

Usage:

n = stringToInteger(s);

string realToString(double d);

Converts a floating-point number into the corresponding string form. For example, calling realToString(23.45) returns "23.45". The conversion is the same as that used for "%G" format in printf.

Usage:

string  s = realToString(d);

double stringToReal(string s);

Converts a string representing a real number into its corresponding value. If the string is not a legal floating-point number or if it contains extraneous characters, stringToReal signals an error condition.

Usage:

d = stringToReal(s);

string trim(string str);

Returns a new string after removing any whitespace characters from the beginning and end of the argument.

Usage:

trimmed = trim(str);

string quoteString(string str);

Returns a quoted string that can be read by the C parser. This string includes double quotes around the entire value, and uses standard escape sequences to indicate special characters.

Usage:

quoted = quoteString(str);

string quoteHTML(string str);

Returns a string that appears correctly in HTML by changing HTML special characters to character entities.

Usage:

quoted = quoteHTML(str);

int stringArrayLength(string array[]);

Returns the length of a NULL-terminated string array.

Usage:

len = stringArrayLength(array);

int searchStringArray(string str, string array[]);

Finds a string in a NULL-terminated string array and returns the first index at which the string appears, or -1 if it is not found.

Usage:

index = searchStringArray(str, array);