defs/si_std/string.h File Reference

A string class and utility functions. More...

#include <si_sys/defs.h>

Go to the source code of this file.

Classes

struct  sc_string
 A dynamic string class. More...

Functions

sc_status sc_string_construct (sc_string *pstr)
sc_status sc_string_constructFrom (sc_string *pstr, const TCHAR *src)
sc_status sc_string_destruct (sc_string *pstr)
sc_status sc_string_assign (sc_string *pstr, const TCHAR *src)
sc_status sc_string_assignChars (sc_string *pstr, const TCHAR *src, s_uint32 nchars)
sc_status sc_string_append (sc_string *pstr, const TCHAR *src)
sc_status sc_string_appendChars (sc_string *pstr, const TCHAR *src, s_uint32 nchars)
sc_status sc_string_prepend (sc_string *pstr, const TCHAR *src)
sc_status sc_string_prependChars (sc_string *pstr, const TCHAR *src, s_uint32 nchars)
sc_status sc_string_detach (sc_string *pstr, TCHAR **ppdst)
sc_status sc_string_toLower (sc_string *pstr)
sc_status sc_string_trimRight (sc_string *pstr)
sc_status sc_string_free (sc_string *pstr)
sc_status sc_string_clear (sc_string *pstr)
sc_status sc_string_setMinCapacity (sc_string *pstr, s_uint32 numChars)
sc_status sc_string_allocCopy (TCHAR **dst, const TCHAR *src)
int iswhitespace (TCHAR c)
const TCHAR * str_advw (const TCHAR *psrc)
const TCHAR * str_advq (const TCHAR *psrc)
const TCHAR * str_advl (const TCHAR *psrc)
int _stricmp (const char *s1, const char *s2)


Detailed Description

A string class and utility functions.


Function Documentation

int _stricmp ( const char *  s1,
const char *  s2 
)

Case independent string comparison.

Parameters:
s1 The pointer to the first string.
s2 The pointer to the second string.
Returns:
non-zero if the strings do not match independent of case, zero otherwise.

int iswhitespace ( TCHAR  c  ) 

returns non-zero if c is a space, tab, newline, or carriage-return character, zero otherwise.

Parameters:
[in] c Character to test.
Returns:
non-zero if c is a whitespace character, zero if not.

sc_status sc_string_allocCopy ( TCHAR **  dst,
const TCHAR *  src 
)

This is a version of 'strdup' that uses sc_status error codes.

Parameters:
[out] dst pointer to a returned string pointer.
[in] src pointer to a string to copy.

sc_status sc_string_append ( sc_string pstr,
const TCHAR *  src 
)

Appends the string src to pstr, growing pstr if necessary.

Parameters:
[in,out] pstr The string being appended to.
[in] src The string to append to pstr.
Note:
No allocation is done if src fits within pstr->capacity_.

sc_status sc_string_appendChars ( sc_string pstr,
const TCHAR *  src,
s_uint32  nchars 
)

Appends a maximum of nchars at src to pstr, growing pstr if necessary.

Parameters:
[in,out] pstr The string being appended to.
[in] src The string to append to pstr.
[in] nchars The maximum number of characters to append.
Note:
If the null character is encountered before nchars are copied, the copy is terminated early, and success is returned.

sc_status sc_string_assign ( sc_string pstr,
const TCHAR *  src 
)

Copies src to pstr, growing pstr if necessary.

Parameters:
[in,out] pstr The string to assign to.
[in] src The string value to copy to pstr.

sc_status sc_string_assignChars ( sc_string pstr,
const TCHAR *  src,
s_uint32  nchars 
)

Copies at most the first nchars characters of src to pstr, growing pstr if necessary.

If NULL is encountered before nchars, the copy is terminated.

Parameters:
[in,out] pstr The string to assign to.
[in] src The string value to copy to pstr.
[in] nchars The maximum number of characters to copy from src.

sc_status sc_string_clear ( sc_string pstr  ) 

Sets the length of the string to 0 without changing the capacity.

Sets length to 0, and str_ to "", without freeing any memory used by the string. Thus, capacity_ remains unchanged.

See also:
sc_string_free
Parameters:
[in,out] pstr The string to clear.

sc_status sc_string_construct ( sc_string pstr  ) 

Constructs an empty string of length 0. Constructs an empty string. No memory allocation is done in this function. The str_ member is set to NULL.

sc_status sc_string_constructFrom ( sc_string pstr,
const TCHAR *  src 
)

Constructs a new string that is a duplicate of src. Constructs an empty string. No memory allocation is done in this function. The str_ member is set to NULL.

Parameters:
[in,out] pstr The string to construct.
[in] src The source string to copy to the newly constructed object.

sc_status sc_string_destruct ( sc_string pstr  ) 

destructs the string, freeing any allocated memory.

sc_status sc_string_detach ( sc_string pstr,
TCHAR **  ppdst 
)

Detached the given string's str_ storage, and returns it in ppdst.

The string pstr is cleared to zero length and capacity, and its current storage is returned in ppdst. The caller becomes responsible for freeing the storage, which can be done with free().

Parameters:
[in,out] pstr The string having its storage detached.
[out] ppdst The location of the string storage in pstr.

sc_status sc_string_free ( sc_string pstr  ) 

Sets the length and capacity of the string to zero, and frees any memory used by the string.

This function clears the string and frees any associated memory. On exit, the state of the string is the same as after running the sc_string_construct function.

See also:
sc_string_construct, and sc_string_clear.
Parameters:
[in,out] pstr The string to free.

sc_status sc_string_prepend ( sc_string pstr,
const TCHAR *  src 
)

Appends the string src to pstr, growing pstr if necessary.

Parameters:
[in,out] pstr The string being appended to.
[in] src The string to append to pstr.
Note:
No allocation is done if src fits within pstr->capacity_.

sc_status sc_string_prependChars ( sc_string pstr,
const TCHAR *  src,
s_uint32  nchars 
)

Prepends a maximum of nchars at src to the start of pstr, growing pstr if necessary.

Parameters:
[in,out] pstr The string being pre-pended to.
[in] src The string to prepend to pstr.
[in] nchars The maximum number of characters to prepend.
Note:
If the null character is encountered before nchars are copied, the copy is terminated early, and success is returned.

sc_status sc_string_setMinCapacity ( sc_string pstr,
s_uint32  numChars 
)

Sets the minimum storage capacity of the string to numChars. Sets the storage size of the str_ buffer to be a minimum of numChars, growing the string if necessary.

Parameters:
[in,out] pstr The string whose capacity may be adjusted.
[in] numChars The minimum number of characters that may be stored at str_.

sc_status sc_string_toLower ( sc_string pstr  ) 

Converts this string to lowercase (in place).

Parameters:
[in,out] pstr The string to convert to lowercase.

sc_status sc_string_trimRight ( sc_string pstr  ) 

Removes any whitespace from the end of the string.

Eliminates whitespace characters from the end of the string. Whitespace includes space, tab, newline, and carriage-return. This is done in place.

Parameters:
[in,out] pstr The string to trim.

const TCHAR* str_advl ( const TCHAR *  psrc  ) 

Advances the given pointer psrc to the next line.

Parameters:
[in] psrc The pointer to advance.
Returns:
psrc advanced to the first character of the next line, or NULL if no newline is found.

const TCHAR* str_advq ( const TCHAR *  psrc  ) 

Advances the given pointer psrc past any quoted text.

Parameters:
[in] psrc The pointer to advance.
Returns:
psrc advanced past quoted text.

const TCHAR* str_advw ( const TCHAR *  psrc  ) 

Advances the given pointer psrc past any whitespace.

Parameters:
[in] psrc The pointer to advance.
Returns:
psrc advanced past whitespace text.


doxygen