strGM - extensions to the string library

NAME

DupStr, stricmp, strnicmp, TokenNumStr, FindTokenStr, FindNthTokenStr, GetNthTokenStr, TokenizeStr, IsTokenPrefStr, SetDelimitersStr, GetDelimitersStr, TokensInStr, ConsStr, ResBufStr, AppBufStr, SizeBufStr, Argv2Str,

SYNOPSIS

#include ''strGM.h'' 


char* DupStr(char * s);  
int   stricmp(const char *s1, const char *s2); 
int   strnicmp(const char *s1, const char *s2,int num); 

int    TokenNumStr(char * str); 
char*  FindTokenStr(char * str, char *tok); 
char*  FindNthTokenStr(char * str,int tokenNo); 
char*  GetNthTokenStr(char * str, int number); 
char** TokenizeStr(char * str);           
int    IsTokenPrefStr(char *token, char * str);    
                           
void  SetDelimitersStr(char * del); 
char* GetDelimitersStr(void); 

char* ConsStr(char * format, ...); 
void   ResBufStr(char * buffer, int size); 
int    AppBufStr(char * format, ...);         
int    SizeBufStr(void);          

char* Argv2Str(int argc, char **argv); 


DESCRIPTION

DupStr

Duplicates a string, ie. allocates memory and copies the contents of the source string. NULL is returned if it's passed to DupStr.

stricmp, strnicmp (written by H. Spencer)

stricmp, strnicmp provide case insensitive string compares. In strincmp at most 'n' characters are compared. Equivalent to strcasecmp, strncasecmp on SUNs.

Tokens (substrings)

In applications, a string is often viewed as a sequence of tokens separated by delimiters (eg. words separated by whitespace characters). The functions described in this section support operations on tokens. White space characters (space,tab,newline) are the default delimiters.

TokenNumStr returns the number of tokens in a string. FindTokenStr(str,tok) retruns a pointer to the first occurence of substring 'tok' in the 'str'; NULL if no occurence is found (equivalent to strstr). FindNthTokenStr(str,tokeNo) retruns a pointer to the n-th token of 'str', NULL if 'str' does not have 'tokenNo' tokens. NB. The input string 'str' must not be freed while the pointer returned by FindNthTokenStr is in use. GetNthTokenStr(str,number) has the same functionality as FindNthTokenStr, but a copy of the 'number'-th token is returned. TokenizeStr(str) returns a NULL terminated array of pointers. N-th element of the array points to a copy of n-th token of str. IsTokenPrefStr(token,str) returns a non-zero value if token is a prefix of 'str'.

The set of delimiters can be defined by a call to SetDelimitersStr(del). GetDelimitersStr() returns the current set.

Building strings

ConsStr has the same functionality as sprintf, but the output string is a/ automatically allocated in ConsStr b/has exactly the necessary size for the resulting string. Internally a large temporary buffer on the stack is used. An error is issued if the internal buffer overflowed Note that this function is not safe in genral! If the buffer overflowed anything can happen (the error message may not be printed etc.). It is the responsibility of the user to make sure the resulting string won't overflow (the size of the internal buffer is set at compile time, the default is 10000). NB. vsprintf and sprintf at least as dangerous as ConsStr (where the overflow is as least tested ex post).

ResBufStr and AppBufStr mimick behaviour of an output stream, but the string is written in the buffer defined by a call to ResBufStr. A new string is appended to the buffer with each call to AppBufStr. The result is similar to concatenating all the strings with strcat, with the difference that the size of the string currently in the buffer is internally maintained and therefore the end of the string does not have to be scanned for. The strcat strategy would be prohibitively slow for long strings. SizeBufStr returns the current length of the string built (unlike strlen the function is constant-time).

Argv2Str(argc,argv) concatenates the strings pointed to by array 'argv' into a single string.

SEE ALSO

BUGS

AUTHOR

George Matas, University of Surrey; g.matas@ee.surrey.ac.uk. stricmp was written by Henry Spencer, modified for ANSI by D'Arcy J.M. Cain
09-Feb-95. Automatically converted by man2html, written by G.Matas (g.matas@ee.surrey.ac.uk)