[ Home | Plans | Meetings | Members | Search | Papers | Links | CyberWear | LocoSoft]
/* * Edward Beale * Cyberjacket Project * 10/7/1998 * * StringLib.h */ /* * A library of useful string functions. * Functions are provided for copying, concatenating, appending, case * conversion and tokenising of strings. */ /* External type declarations. */ struct ts_struct; typedef struct ts_struct TokenStruct; /* External function prototypes. */ int String_Copy(const char *from, char **to); /* * Description: This function allocates space for a new string of * standard length (given by STRING_MAX in Constants.h) * and copies the contents to string `from' into it. * The new string is returned as `to'. * * Pre-conditions: `from' is null-terminated. * * Post-conditions: Space for a new string, *to, is allocated and the * contents of string `from' are copied into it. * * Return values: 0 Success. * -3 Memory allocation error. */ int String_ToLower(char *string); /* * Description: This function converts a string to lower case. * The original string is altered and no new memory * is allocated. * * Pre-conditions: `string' is null-terminated. * * Post-conditions: Each alphabetic character in `string' is converted * to lower case in place. Return value is 0. */ int String_Concat(const char *str1, const char *str2, char *result); /* * Description: This function concatenates `str1' with `str2' such that * the characters of `str2' follow those of `str1'. * Neither `str1' nor `str2' is altered. `result' is * overwritten with the combined string. No new memory is * allocated. * * Pre-conditions: The two input strings are null-terminated. * * Post-conditions: `result' is overwritten by str1 concatenated with str2. * The two original strings are not affected. * Return value is 0. */ int String_Append(char *original, const char *addition); /* * Description: This function appends the string `addition' onto the * end of 'original', altering `original'. No new memory * is allocated. * * Pre-conditions: Both of the given strings are null-terminated. * * Post-conditions: String `addition' is appended onto the end of string * `original'. Return value is 0. */ int String_SetupToken(const char *string, const char *separators, TokenStruct **tokstr); /* * Description: This function is used to set up `string' for * tokenisation. This allows `string' to be split up * into tokens using the String_NextToken() function. * * Tokens: A token is a substring of `string'. It begins either at * at the start of `string' or with one or more of the * characters in `separators'. It ends either at the end * of `string' or with on or more `separators'. * * Pre-conditions: `string' is a null-terminated string to be split into * tokens. * `separators' is a null-terminated list of characters * used as token separators by subsequent calls to * String_NextToken(). * * Post-conditions: Memory will be allocated for a new TokenStruct and the * pointer *tokstr set to point to this. * When this pointer is passed to subsequent calls of * String_NextToken(), the tokens in `string' will be * returned one at a time. * * Return values: 0 Success. * -3 Memory allocation error. */ int String_NextToken(TokenStruct **tokstr, char **token); /* * Description: Following a successful call to String_SetupToken(), * this function can be used repeatedly to return the * tokens. At each call it will return the next token and * update *tokstr. * * Pre-conditions: *tokstr has been set up with String_SetupToken(). * The last call to String_NextToken() - if any - did * not return 1 (no more tokens). * * Post-conditions: *token is set to point to the next token (if there are * any more). If there are no more tokens, then the memory * allocated to *tokstr will be deallocated and the pointer * set to NULL. * * Return values: 0 Success. * 1 There are no more tokens. Do not use *tokstr again. * -1 Error: *tokstr has already been deallocated. * * Note: *token does not need to be allocated space and should * not be deallocated either. It is a pointer into another * string. */
The material displayed is provided 'as is' and is subject to use restrictions.
For problems or questions regarding this web contact Cliff Randell.
Last updated: January 14, 2000.
ęCopyright Hewlett-Packard 1997-2000.