Bristol Wearable Computing

[ Home | Plans | Meetings | Members | Search | Papers | Links | CyberWear | LocoSoft]


StringLib

/*
 *      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.
 */


unicrest.gif (4191 bytes)

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.
logoep.gif (1404 bytes)
ęCopyright Hewlett-Packard 1997-2000.