# The "st" Package

These routines are meant to supplement the standard C library str* routines Since each version of Unix has a different set of "extra" string functions, this package is meant to bridge the gap, and provides some of the more useful "extras".

Library: karma
Link With: -lkarma

#### Functions

st_expr_expand | Expand an expression using Borne Shell-like unquoted rules.
st_find | Search a list of strings for a string.
st_chr | Search a string for the first occurrence of a character.
st_cmp_wild | Compare strings with wildcard support.
st_cspn | Find maximum leading segment in string with exclusion.
st_icmp | Compare strings, ignoring case.
st_lwr | Convert a string to lowercase.
st_nicmp | Compare strings, ignoring case, up to a specified length.
st_nupr | Convert a string to uppercase, up to a specified length.
st_nlwr | Convert a string to lowercase, up to a specified length.
st_pbrk | Search a string for a character from a set.
st_rchr | Search a string for the last occurrence of a character.
st_spn | Find maximum leading segment in string with inclusion.
st_tok | Extract token from string.
st_tol | Convert a string to a long integer.
st_upr | Convert a string to uppercase.
st_dup | Make a duplicate copy of a string.
st_qsort | Perform a quicksort on an array of strings.

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag st_expr_expand (char *output, unsigned int length, CONST char *input, CONST char *(*get_variable) (CONST char *variable, void *info), void *info, FILE *errfp)

Expand an expression using Borne Shell-like unquoted rules.

Parameters:

- output : The output expanded expression is written here.
- length : The size of the output buffer.
- input : The input expression. This may equal output.
- get_variable : A function which will be used to get variable values. If this returns NULL, the environment is searched instead. If this is NULL, only the environment is searched.
- info : An arbitrary pointer passed to get_variable.
- errfp : Diagnostic messages are written here. If this is NULL the global stderr is used instead.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

unsigned int st_find ( CONST char **string_list, unsigned int list_length, CONST char *string, int (*function) () )

Search a list of strings for a string.

Parameters:

- string_list : The list of strings to search.
- list_length : The length of the string list.
- string : The string to search for.
- function : The function to use for string comparisons. This has the same interface as the strcmp function.

Returns: The index of the found string in the string list. If no match is found, the list_length is returned. The routine returns on the first match.
Multithreading Level: Unsafe

CONST char * st_chr (CONST char *string, char c)

Search a string for the first occurrence of a character.

Parameters:

- string : The string to search.
- c : The character to search for.

Returns: A pointer to the found character in the string. If no match is found, NULL is returned.
Multithreading Level: Unsafe

int st_cmp_wild (CONST char *a, CONST char *b)

Compare strings with wildcard support.

Parameters:

- a : One of the strings. Wildcards are permitted.
- b : The other string. Wildcards are not permitted.

Returns: The difference between the strings.
Multithreading Level: Unsafe

int st_cspn (CONST char *string, CONST char *charset)

Find maximum leading segment in string with exclusion.

Parameters:

- string : The string.
- charset : The set of exclusion characters.

Returns: The number of characters in the leading segment.
Multithreading Level: Unsafe

int st_icmp (CONST char *string1, CONST char *string2)

Compare strings, ignoring case.

Parameters:

- string1 : One of the strings.
- string2 : The other string.

Returns: The comparison value. 0 indicates equality.
Multithreading Level: Unsafe

char * st_lwr (char *string)

Convert a string to lowercase.

Parameters:

- string : The string.

Returns: The address of the string.
Multithreading Level: Unsafe

int st_nicmp (CONST char *string1, CONST char *string2, int str_len)

Compare strings, ignoring case, up to a specified length.

Parameters:

- string1 : One of the strings.
- string2 : The other string.
- str_len : The maximum number of characters to compare.

Returns: The comparison value. 0 indicates equality.
Multithreading Level: Unsafe

char * st_nupr (char *string, int str_len)

Convert a string to uppercase, up to a specified length.

Parameters:

- string : The string.
- str_len : The maximum number of characters to convert.

Returns: The address of the string.
Multithreading Level: Unsafe

char * st_nlwr (char *string, int str_len)

Convert a string to lowercase, up to a specified length.

Parameters:

- string : The string.
- str_len : The maximum number of characters to convert.

Returns: The address of the string.
Multithreading Level: Unsafe

char * st_pbrk (CONST char *string, CONST char *brkset)

Search a string for a character from a set.

Parameters:

- string : The string to search.
- brkset : The set of characters to search for.

Returns: A pointer to the found character in the string. If no match is found, NULL is returned.
Multithreading Level: Unsafe

CONST char * st_rchr (CONST char *string, char c)

Search a string for the last occurrence of a character.

Parameters:

- string : The string to search.
- c : The character to search for.

Returns: A pointer to the found character in the string. If no match is found, NULL is returned.
Multithreading Level: Unsafe

int st_spn (CONST char *string, CONST char *charset)

Find maximum leading segment in string with inclusion.

Parameters:

- string : The string.
- charset : The set of inclusion characters.

Returns: The number of characters in the leading segment.
Multithreading Level: Unsafe

char * st_tok (char *string, CONST char *sepset)

This routine will break a string into a series of tokens. This routine should be called until no more tokens are found.

Parameters:

- string : The string. On subsequent calls (for a series of tokens), NULL should be passed.
- sepset : The set of delimiters (separators between tokens).

Returns: A pointer to the next token. NULL is returned if no tokens are found.
Multithreading Level: Unsafe

long st_tol (CONST char *str, char **ptr, int base)

Convert a string to a long integer.

Parameters:

- str : The string.
- ptr : A pointer to the first invalid character is written here. If this is NULL, nothing is written here.
- base : The base of the number system.

Returns: The integer value.
Multithreading Level: Unsafe

char * st_upr (char *string)

Convert a string to uppercase.

Parameters:

- string : The string.

Returns: The address of the string.
Multithreading Level: Unsafe

char * st_dup (CONST char *input)

Make a duplicate copy of a string.

Parameters:

- string : The input string.

Returns: A pointer to a copy of the string (allocated using m_alloc) on success, else NULL.
Multithreading Level: Unsafe

void st_qsort (char **v, int left, int right)

Perform a quicksort on an array of strings.

Parameters:

- v : The array of strings.
- left : The left string index.
- right : The right string index.

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page