CrystalSpace

Public API Reference

Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

csString Class Reference

This is a string class with a range of useful operators and type-safe overloads. More...

#include <csstring.h>

List of all members.

Public Methods

void SetCapacity (size_t NewSize)
 Advise the string that it should allocate enough space to hold up to NewSize characters.

size_t GetCapacity () const
 Return the current capacity.

void SetGrowsBy (size_t)
 Advise the string that it should grow by approximately this many bytes when more space is required.

size_t GetGrowsBy () const
 Return the number of bytes by which the string grows.

void SetGrowsExponentially (bool b)
 Tell the string to re-size its buffer exponentially as needed.

bool GetGrowsExponentially () const
 Returns true if exponential growth is enabled.

void Free ()
 Free the memory allocated for the string.

csString & Truncate (size_t Len)
 Truncate the string.

csString & Reclaim ()
 Set string buffer capacity to hold exactly the current content.

csString & Clear ()
 Clear the string (so that it contains only a null terminator).

char const * GetData () const
 Get a pointer to the null-terminated character array.

char * GetData ()
 Get a pointer to the null-terminated character array.

char const * GetDataSafe () const
 Get a pointer to the null-terminated character array.

size_t Length () const
 Query string length.

bool IsEmpty () const
 Check if string is empty.

char & operator[] (size_t n)
 Get a modifiable reference to n'th character.

char operator[] (size_t n) const
 Get n'th character.

void SetAt (size_t n, const char c)
 Set the n'th character.

char GetAt (size_t n) const
 Get the n'th character.

csString & DeleteAt (size_t Pos, size_t Count=1)
 Delete a range of characters from the string.

csString & Insert (size_t Pos, const csString &Str)
 Insert another string into this one.

csString & Insert (size_t Pos, const char *Str)
 Insert another string into this one.

csString & Insert (size_t Pos, char C)
 Insert another string into this one.

csString & Overwrite (size_t Pos, const csString &Str)
 Overlay another string onto a part of this string.

csString & Append (const char *Str, size_t Count=(size_t)-1)
 Append a null-terminated C-string to this one.

csString & Append (const csString &Str, size_t Count=(size_t)-1)
 Append a string to this one.

csString & Append (char c)
 Append a signed character to this string.

csString & Append (unsigned char c)
 Append an unsigned character to this string.

csString Slice (size_t start, size_t len) const
 Copy and return a portion of this string.

void SubString (csString &sub, size_t start, size_t len) const
 Copy a portion of this string.

size_t FindFirst (char c, size_t p=0) const
 Find the first occurrence of a character in the string.

size_t FindLast (char c, size_t p=(size_t)-1) const
 Find the last occurrence of a character in the string.

csString & Append (bool b)
 Append a boolean (as a number -- 1 or 0) to this string.

csString & Replace (const csString &Str, size_t Count=(size_t)-1)
 Replace contents of this string with the contents of another.

csString & Replace (const char *Str, size_t Count=(size_t)-1)
 Replace contents of this string with the contents of another.

bool Compare (const csString &iStr) const
 Check if another string is equal to this one.

bool Compare (const char *iStr) const
 Check if a null-terminated C- string is equal to this string.

bool CompareNoCase (const csString &iStr) const
 Check if another string is equal to this one.

bool CompareNoCase (const char *iStr) const
 Check if a null-terminated C- string is equal to this string.

 csString ()
 Create an empty csString object.

 csString (size_t Length)
 Create a csString object and reserve space for at least Length characters.

 csString (const csString &copy)
 Copy constructor.

 csString (const char *src)
 Create a csString object from a null-terminated C string.

 csString (char c)
 Create a csString object from a single signed character.

 csString (unsigned char c)
 Create a csString object from a single unsigned character.

virtual ~csString ()
 Destroy the csString.

csString Clone () const
 Get a copy of this string.

csString & LTrim ()
 Trim leading whitespace.

csString & RTrim ()
 Trim trailing whitespace.

csString & Trim ()
 Trim leading and trailing whitespace.

csString & Collapse ()
 Trim leading and trailing whitespace, and collapse all internal whitespace to a single space.

csString & Format (const char *format,...)
 Format this string using sprintf()-style formatting directives.

csString & FormatV (const char *format, va_list args)
 Format this string using sprintf() formatting directives in a va_list.

csString & PadLeft (size_t NewSize, char PadChar= ' ')
 Pad to a specified size with leading characters.

csString AsPadLeft (size_t NewSize, char PadChar= ' ') const
 Return a copy of this string formatted with PadLeft().

csString & PadRight (size_t NewSize, char PadChar= ' ')
 Pad to a specified size with trailing characters.

csString AsPadRight (size_t NewSize, char PadChar= ' ') const
 Return a copy of this string formatted with PadRight().

csString & PadCenter (size_t NewSize, char PadChar= ' ')
 Pad to a specified size with leading and trailing characters so as to center the string.

csString AsPadCenter (size_t NewSize, char PadChar= ' ') const
 Return a copy of this string formatted with PadCenter().

csString operator+ (const csString &iStr) const
 Add another string to this one and return the result as a new string.

 operator const char * () const
 Get a pointer to the null-terminated character array.

bool operator== (const csString &Str) const
 Check if another string is equal to this one.

bool operator== (const char *Str) const
 Check if another string is equal to this one.

bool operator!= (const csString &Str) const
 Check if another string is not equal to this one.

bool operator!= (const char *Str) const
 Check if another string is not equal to this one.

csString & Downcase ()
 Convert this string to lower-case.

csString & Upcase ()
 Convert this string to upper-case.

char * Detach ()
 Detach the low-level null-terminated C-string buffer from the csString object.

csString & Append (short n)
 Append the value, in formatted form, to this string.

csString & Append (unsigned short n)
 Append the value, in formatted form, to this string.

csString & Append (int n)
 Append the value, in formatted form, to this string.

csString & Append (unsigned int n)
 Append the value, in formatted form, to this string.

csString & Append (long n)
 Append the value, in formatted form, to this string.

csString & Append (unsigned long n)
 Append the value, in formatted form, to this string.

csString & Append (float n)
 Append the value, in formatted form, to this string.

csString & Append (double n)
 Append the value, in formatted form, to this string.

csString & Replace (char s)
 Replace contents of this string with the value in formatted form.

csString & Replace (unsigned char s)
 Replace contents of this string with the value in formatted form.

csString & Replace (short s)
 Replace contents of this string with the value in formatted form.

csString & Replace (unsigned short s)
 Replace contents of this string with the value in formatted form.

csString & Replace (int s)
 Replace contents of this string with the value in formatted form.

csString & Replace (unsigned int s)
 Replace contents of this string with the value in formatted form.

csString & Replace (long s)
 Replace contents of this string with the value in formatted form.

csString & Replace (unsigned long s)
 Replace contents of this string with the value in formatted form.

csString & Replace (float s)
 Replace contents of this string with the value in formatted form.

csString & Replace (double s)
 Replace contents of this string with the value in formatted form.

csString & Replace (bool s)
 Replace contents of this string with the value in formatted form.

const csString & operator= (const csString &s)
 Assign a formatted value to this string.

const csString & operator= (const char *s)
 Assign a formatted value to this string.

const csString & operator= (char s)
 Assign a formatted value to this string.

const csString & operator= (unsigned char s)
 Assign a formatted value to this string.

const csString & operator= (short s)
 Assign a formatted value to this string.

const csString & operator= (unsigned short s)
 Assign a formatted value to this string.

const csString & operator= (int s)
 Assign a formatted value to this string.

const csString & operator= (unsigned int s)
 Assign a formatted value to this string.

const csString & operator= (long s)
 Assign a formatted value to this string.

const csString & operator= (unsigned long s)
 Assign a formatted value to this string.

const csString & operator= (float s)
 Assign a formatted value to this string.

const csString & operator= (double s)
 Assign a formatted value to this string.

const csString & operator= (bool s)
 Assign a formatted value to this string.

csString & operator+= (const csString &s)
 Append a formatted value to this string.

csString & operator+= (const char *s)
 Append a formatted value to this string.

csString & operator+= (char s)
 Append a formatted value to this string.

csString & operator+= (unsigned char s)
 Append a formatted value to this string.

csString & operator+= (short s)
 Append a formatted value to this string.

csString & operator+= (unsigned short s)
 Append a formatted value to this string.

csString & operator+= (int s)
 Append a formatted value to this string.

csString & operator+= (unsigned int s)
 Append a formatted value to this string.

csString & operator+= (long s)
 Append a formatted value to this string.

csString & operator+= (unsigned long s)
 Append a formatted value to this string.

csString & operator+= (float s)
 Append a formatted value to this string.

csString & operator+= (double s)
 Append a formatted value to this string.

csString & operator+= (bool s)
 Append a formatted value to this string.


Static Public Methods

csString Format (short v)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned short v)
 Format this value using a sprintf() formatting directive.

csString Format (int v)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned int v)
 Format this value using a sprintf() formatting directive.

csString Format (long v)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned long v)
 Format this value using a sprintf() formatting directive.

csString Format (float v)
 Format this value using a sprintf() formatting directive.

csString Format (double v)
 Format this value using a sprintf() formatting directive.

csString Format (short v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned short v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (int v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned int v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (long v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (unsigned long v, int width, int prec=0)
 Format this value using a sprintf() formatting directive.

csString Format (float v, int width, int prec=6)
 Format this value using a sprintf() formatting directive.

csString Format (double v, int width, int prec=6)
 Format this value using a sprintf() formatting directive.

csString PadLeft (const csString &v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (const char *v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (char v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (unsigned char v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (short v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (unsigned short v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (int v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (unsigned int v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (long v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (unsigned long v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (float v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (double v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadLeft (bool v, size_t iNewSize, char iChar=' ')
 Return a new left-padded string representation of a basic type.

csString PadRight (const csString &v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (const char *v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (char v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (unsigned char v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (short v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (unsigned short v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (int v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (unsigned int v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (long v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (unsigned long v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (float v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (double v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadRight (bool v, size_t iNewSize, char iChar=' ')
 Return a new right-padded string representation of a basic type.

csString PadCenter (const csString &v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (const char *v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (char v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (unsigned char v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (short v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (unsigned short v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (int v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (unsigned int v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (long v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (unsigned long v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (float v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (double v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.

csString PadCenter (bool v, size_t iNewSize, char iChar=' ')
 Return a new left+right padded string representation of a basic type.


Detailed Description

This is a string class with a range of useful operators and type-safe overloads.

Strings may contain arbitary binary data, including null bytes. It also guarantees that a null-terminator always follows the last stored character, thus you can safely use the return value from GetData() and `operator char const *()' in calls to functions expecting C strings. The implicit null terminator is not included in the character count returned by Length().

Like a typical C character string pointer, csString can also represent a null pointer. This allows a non-string to be distinguished from an empty (zero-length) string. The csString will represent a null-pointer in the following cases:

Definition at line 54 of file csstring.h.


Constructor & Destructor Documentation

csString::csString   [inline]
 

Create an empty csString object.

Remarks:
The newly constructed string represents a null-pointer.

Definition at line 481 of file csstring.h.

csString::csString size_t    Length [inline]
 

Create a csString object and reserve space for at least Length characters.

Remarks:
The newly constructed string represents a non-null zero-length string.

Definition at line 489 of file csstring.h.

csString::csString const csString &    copy [inline]
 

Copy constructor.

Remarks:
The newly constructed string will represent a null-pointer if and only if the template string represented a null-pointer.

Definition at line 498 of file csstring.h.

csString::csString const char *    src [inline]
 

Create a csString object from a null-terminated C string.

Remarks:
The newly constructed string will represent a null-pointer if and only if the input argument is a null-pointer.

Definition at line 507 of file csstring.h.

csString::csString char    c [inline]
 

Create a csString object from a single signed character.

Definition at line 512 of file csstring.h.

csString::csString unsigned char    c [inline]
 

Create a csString object from a single unsigned character.

Definition at line 517 of file csstring.h.

virtual csString::~csString   [virtual]
 

Destroy the csString.


Member Function Documentation

csString& csString::Append bool    b [inline]
 

Append a boolean (as a number -- 1 or 0) to this string.

Definition at line 375 of file csstring.h.

csString& csString::Append double    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 369 of file csstring.h.

csString& csString::Append float    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 368 of file csstring.h.

csString& csString::Append unsigned long    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 367 of file csstring.h.

csString& csString::Append long    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 366 of file csstring.h.

csString& csString::Append unsigned int    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 365 of file csstring.h.

csString& csString::Append int    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 364 of file csstring.h.

csString& csString::Append unsigned short    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 363 of file csstring.h.

csString& csString::Append short    n [inline]
 

Append the value, in formatted form, to this string.

Definition at line 362 of file csstring.h.

csString& csString::Append unsigned char    c [inline]
 

Append an unsigned character to this string.

Returns:
Reference to itself.

Definition at line 316 of file csstring.h.

csString& csString::Append char    c [inline]
 

Append a signed character to this string.

Returns:
Reference to itself.

Definition at line 309 of file csstring.h.

csString& csString::Append const csString &    Str,
size_t    Count = (size_t)-1
 

Append a string to this one.

Parameters:
Str  String which will be appended.
Count  Number of characters from Str to append; if -1 (the default), then all characters from Str will be appended.
Returns:
Reference to itself.

csString& csString::Append const char *    Str,
size_t    Count = (size_t)-1
 

Append a null-terminated C-string to this one.

Parameters:
Str  String which will be appended.
Count  Number of characters from Str to append; if -1 (the default), then all characters from Str will be appended.
Returns:
Reference to itself.

Referenced by operator+(), and operator+().

csString csString::AsPadCenter size_t    NewSize,
char    PadChar = ' '
const
 

Return a copy of this string formatted with PadCenter().

csString csString::AsPadLeft size_t    NewSize,
char    PadChar = ' '
const
 

Return a copy of this string formatted with PadLeft().

csString csString::AsPadRight size_t    NewSize,
char    PadChar = ' '
const
 

Return a copy of this string formatted with PadRight().

csString& csString::Clear   [inline]
 

Clear the string (so that it contains only a null terminator).

Returns:
Reference to itself.
Remarks:
This is rigidly equivalent to Truncate(0), but more idiomatic in terms of human language.

Definition at line 159 of file csstring.h.

csString csString::Clone   const [inline]
 

Get a copy of this string.

Remarks:
The newly constructed string will represent a null-pointer if and only if this string represents a null-pointer.

Definition at line 529 of file csstring.h.

Referenced by operator+().

csString& csString::Collapse  
 

Trim leading and trailing whitespace, and collapse all internal whitespace to a single space.

Returns:
Reference to itself.

bool csString::Compare const char *    iStr const [inline]
 

Check if a null-terminated C- string is equal to this string.

Parameters:
iStr  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-sensitive.

Definition at line 447 of file csstring.h.

bool csString::Compare const csString &    iStr const [inline]
 

Check if another string is equal to this one.

Parameters:
iStr  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-sensitive.

Definition at line 429 of file csstring.h.

References GetData(), and Length().

bool csString::CompareNoCase const char *    iStr const [inline]
 

Check if a null-terminated C- string is equal to this string.

Parameters:
iStr  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-insensitive.

Definition at line 474 of file csstring.h.

bool csString::CompareNoCase const csString &    iStr const [inline]
 

Check if another string is equal to this one.

Parameters:
iStr  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-insensitive.

Definition at line 456 of file csstring.h.

References GetData(), and Length().

csString& csString::DeleteAt size_t    Pos,
size_t    Count = 1
 

Delete a range of characters from the string.

Parameters:
Pos  Beginning of range to be deleted (zero-based).
Count  Number of characters to delete.
Returns:
Reference to itself.

char* csString::Detach   [inline]
 

Detach the low-level null-terminated C-string buffer from the csString object.

Returns:
The low-level null-terminated C-string buffer, or zero if this string represents a null-pointer. See the class description for a discussion about how and when the string will represent a null-pointer.
Remarks:
The caller of this function becomes the owner of the returned string buffer and is responsible for destroying it via `delete[]' when no longer needed.

Definition at line 843 of file csstring.h.

csString& csString::Downcase  
 

Convert this string to lower-case.

Returns:
Reference to itself.

size_t csString::FindFirst char    c,
size_t    p = 0
const
 

Find the first occurrence of a character in the string.

Parameters:
c  Character to locate.
p  Start position of search (default 0).
Returns:
First position of character, or (size_t)-1 if not found.

size_t csString::FindLast char    c,
size_t    p = (size_t)-1
const
 

Find the last occurrence of a character in the string.

Parameters:
c  Character to locate.
p  Start position of reverse search. Specify (size_t)-1 if you want the search to begin at the very end of string.
Returns:
Last position of character, or (size_t)-1 if not found.

csString csString::Format double    v,
int    width,
int    prec = 6
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format float    v,
int    width,
int    prec = 6
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned long    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format long    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned int    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format int    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned short    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format short    v,
int    width,
int    prec = 0
[static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format double    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format float    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned long    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format long    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned int    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format int    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format unsigned short    v [static]
 

Format this value using a sprintf() formatting directive.

csString csString::Format short    v [static]
 

Format this value using a sprintf() formatting directive.

csString& csString::Format const char *    format,
...   
 

Format this string using sprintf()-style formatting directives.

Returns:
Reference to itself.
Remarks:
Automatically allocates sufficient memory to hold result. Newly formatted string replaces previous string value.

csString& csString::FormatV const char *    format,
va_list    args
 

Format this string using sprintf() formatting directives in a va_list.

Returns:
Reference to itself.
Remarks:
Automatically allocates sufficient memory to hold result. Newly formatted string replaces previous string value.

void csString::Free  
 

Free the memory allocated for the string.

Remarks:
Following a call to this method, invocations of GetData() and 'operator char const*' will return a null pointer (until some new content is added to the string).

char csString::GetAt size_t    n const [inline]
 

Get the n'th character.

Definition at line 239 of file csstring.h.

size_t csString::GetCapacity   const [inline]
 

Return the current capacity.

Definition at line 89 of file csstring.h.

char* csString::GetData   [inline]
 

Get a pointer to the null-terminated character array.

Returns:
A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.
Remarks:
See the class description for a discussion about how and when the string will represent a null-pointer.
Warning:
This returns a non-const pointer, so use this function with care!
Deprecated:
Use the 'const' version of GetData() instead.

Definition at line 181 of file csstring.h.

char const* csString::GetData   const [inline]
 

Get a pointer to the null-terminated character array.

Returns:
A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.
Remarks:
See the class description for a discussion about how and when the string will represent a null-pointer.

Definition at line 169 of file csstring.h.

Referenced by Compare(), and CompareNoCase().

char const* csString::GetDataSafe   const [inline]
 

Get a pointer to the null-terminated character array.

Returns:
A C-string pointer to the null-terminated character array.
Remarks:
Unlike GetData(), this will always return a valid, non-null C-string, even if the underlying representation is that of a null-pointer (in which case, it will return a zero-length C-string. This is a handy convenience which makes it possible to use the result directly without having to perform a null check first.

Definition at line 193 of file csstring.h.

size_t csString::GetGrowsBy   const [inline]
 

Return the number of bytes by which the string grows.

Definition at line 102 of file csstring.h.

bool csString::GetGrowsExponentially   const [inline]
 

Returns true if exponential growth is enabled.

Definition at line 113 of file csstring.h.

csString& csString::Insert size_t    Pos,
char    C
 

Insert another string into this one.

Parameters:
Pos  Position at which to insert the other string (zero-based).
C  Character to insert.
Returns:
Reference to itself.

csString& csString::Insert size_t    Pos,
const char *    Str
 

Insert another string into this one.

Parameters:
Pos  Position at which to insert the other string (zero-based).
Str  String to insert.
Returns:
Reference to itself.

csString& csString::Insert size_t    Pos,
const csString &    Str
 

Insert another string into this one.

Parameters:
Pos  Position at which to insert the other string (zero-based).
Str  String to insert.
Returns:
Reference to itself.

bool csString::IsEmpty   const [inline]
 

Check if string is empty.

Returns:
True if the string is empty; false if it is not.
Remarks:
This is rigidly equivalent to the expression 'Length() == 0'.

Definition at line 209 of file csstring.h.

size_t csString::Length   const [inline]
 

Query string length.

Returns:
The string length.
Remarks:
The returned length does not count the implicit null terminator.

Definition at line 201 of file csstring.h.

Referenced by Compare(), and CompareNoCase().

csString& csString::LTrim  
 

Trim leading whitespace.

Returns:
Reference to itself.
Remarks:
This is equivalent to Truncate(n) where 'n' is the last non-whitespace character, or zero if the string is composed entirely of whitespace.

csString::operator const char *   const [inline]
 

Get a pointer to the null-terminated character array.

Returns:
A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.
Remarks:
See the class description for a discussion about how and when the string will represent a null-pointer.

Definition at line 786 of file csstring.h.

bool csString::operator!= const char *    Str const [inline]
 

Check if another string is not equal to this one.

Parameters:
Str  Other string.
Returns:
False if they are equal; true if not.
Remarks:
The comparison is case-sensitive.

Definition at line 819 of file csstring.h.

bool csString::operator!= const csString &    Str const [inline]
 

Check if another string is not equal to this one.

Parameters:
Str  Other string.
Returns:
False if they are equal; true if not.
Remarks:
The comparison is case-sensitive.

Definition at line 811 of file csstring.h.

csString csString::operator+ const csString &    iStr const [inline]
 

Add another string to this one and return the result as a new string.

Definition at line 776 of file csstring.h.

References Append().

csString& csString::operator+= bool    s [inline]
 

Append a formatted value to this string.

Definition at line 770 of file csstring.h.

csString& csString::operator+= double    s [inline]
 

Append a formatted value to this string.

Definition at line 768 of file csstring.h.

csString& csString::operator+= float    s [inline]
 

Append a formatted value to this string.

Definition at line 767 of file csstring.h.

csString& csString::operator+= unsigned long    s [inline]
 

Append a formatted value to this string.

Definition at line 766 of file csstring.h.

csString& csString::operator+= long    s [inline]
 

Append a formatted value to this string.

Definition at line 765 of file csstring.h.

csString& csString::operator+= unsigned int    s [inline]
 

Append a formatted value to this string.

Definition at line 764 of file csstring.h.

csString& csString::operator+= int    s [inline]
 

Append a formatted value to this string.

Definition at line 763 of file csstring.h.

csString& csString::operator+= unsigned short    s [inline]
 

Append a formatted value to this string.

Definition at line 762 of file csstring.h.

csString& csString::operator+= short    s [inline]
 

Append a formatted value to this string.

Definition at line 761 of file csstring.h.

csString& csString::operator+= unsigned char    s [inline]
 

Append a formatted value to this string.

Definition at line 760 of file csstring.h.

csString& csString::operator+= char    s [inline]
 

Append a formatted value to this string.

Definition at line 759 of file csstring.h.

csString& csString::operator+= const char *    s [inline]
 

Append a formatted value to this string.

Definition at line 758 of file csstring.h.

csString& csString::operator+= const csString &    s [inline]
 

Append a formatted value to this string.

Definition at line 757 of file csstring.h.

const csString& csString::operator= bool    s [inline]
 

Assign a formatted value to this string.

Definition at line 746 of file csstring.h.

const csString& csString::operator= double    s [inline]
 

Assign a formatted value to this string.

Definition at line 744 of file csstring.h.

const csString& csString::operator= float    s [inline]
 

Assign a formatted value to this string.

Definition at line 743 of file csstring.h.

const csString& csString::operator= unsigned long    s [inline]
 

Assign a formatted value to this string.

Definition at line 742 of file csstring.h.

const csString& csString::operator= long    s [inline]
 

Assign a formatted value to this string.

Definition at line 741 of file csstring.h.

const csString& csString::operator= unsigned int    s [inline]
 

Assign a formatted value to this string.

Definition at line 740 of file csstring.h.

const csString& csString::operator= int    s [inline]
 

Assign a formatted value to this string.

Definition at line 739 of file csstring.h.

const csString& csString::operator= unsigned short    s [inline]
 

Assign a formatted value to this string.

Definition at line 738 of file csstring.h.

const csString& csString::operator= short    s [inline]
 

Assign a formatted value to this string.

Definition at line 737 of file csstring.h.

const csString& csString::operator= unsigned char    s [inline]
 

Assign a formatted value to this string.

Definition at line 736 of file csstring.h.

const csString& csString::operator= char    s [inline]
 

Assign a formatted value to this string.

Definition at line 735 of file csstring.h.

const csString& csString::operator= const char *    s [inline]
 

Assign a formatted value to this string.

Definition at line 734 of file csstring.h.

const csString& csString::operator= const csString &    s [inline]
 

Assign a formatted value to this string.

Definition at line 733 of file csstring.h.

bool csString::operator== const char *    Str const [inline]
 

Check if another string is equal to this one.

Parameters:
Str  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-sensitive.

Definition at line 803 of file csstring.h.

bool csString::operator== const csString &    Str const [inline]
 

Check if another string is equal to this one.

Parameters:
Str  Other string.
Returns:
True if they are equal; false if not.
Remarks:
The comparison is case-sensitive.

Definition at line 795 of file csstring.h.

char csString::operator[] size_t    n const [inline]
 

Get n'th character.

Definition at line 220 of file csstring.h.

char& csString::operator[] size_t    n [inline]
 

Get a modifiable reference to n'th character.

Definition at line 213 of file csstring.h.

csString& csString::Overwrite size_t    Pos,
const csString &    Str
 

Overlay another string onto a part of this string.

Parameters:
Pos  Position at which to insert the other string (zero-based).
Str  String which will be overlayed atop this string.
Returns:
Reference to itself.
Remarks:
The target string will grow as necessary to accept the new string.

csString csString::PadCenter bool    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter double    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter float    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter unsigned long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter unsigned int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter unsigned short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter unsigned char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter const char *    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString csString::PadCenter const csString &    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left+right padded string representation of a basic type.

csString& csString::PadCenter size_t    NewSize,
char    PadChar = ' '
 

Pad to a specified size with leading and trailing characters so as to center the string.

Parameters:
NewSize  Size to which the string should grow.
PadChar  Character with which to pad the string (default is space).
Returns:
Reference to itself.
Remarks:
Never shortens the string. If NewSize is less than or equal to Length(), nothing happens. If the left and right sides can not be padded equally, then the right side will gain the extra one-character padding.

csString csString::PadLeft bool    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft double    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft float    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft unsigned long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft unsigned int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft unsigned short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft unsigned char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft const char *    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString csString::PadLeft const csString &    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new left-padded string representation of a basic type.

csString& csString::PadLeft size_t    NewSize,
char    PadChar = ' '
 

Pad to a specified size with leading characters.

Parameters:
NewSize  Size to which the string should grow.
PadChar  Character with which to pad the string (default is space).
Returns:
Reference to itself.
Remarks:
Never shortens the string. If NewSize is less than or equal to Length(), nothing happens.

csString csString::PadRight bool    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight double    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight float    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight unsigned long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight long    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight unsigned int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight int    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight unsigned short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight short    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight unsigned char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight char    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight const char *    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString csString::PadRight const csString &    v,
size_t    iNewSize,
char    iChar = ' '
[static]
 

Return a new right-padded string representation of a basic type.

csString& csString::PadRight size_t    NewSize,
char    PadChar = ' '
 

Pad to a specified size with trailing characters.

Parameters:
NewSize  Size to which the string should grow.
PadChar  Character with which to pad the string (default is space).
Returns:
Reference to itself.
Remarks:
Never shortens the string. If NewSize is less than or equal to Length(), nothing happens.

csString& csString::Reclaim  
 

Set string buffer capacity to hold exactly the current content.

Returns:
Reference to itself.
Remarks:
If the string length is greater than zero, then the buffer's capacity will be adjusted to exactly that size. If the string length is zero, then this is equivalent to an invocation of Free(), which means that GetData() and 'operator char const*' will return a null pointer after reclamation.

csString& csString::Replace bool    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 418 of file csstring.h.

csString& csString::Replace double    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 416 of file csstring.h.

csString& csString::Replace float    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 415 of file csstring.h.

csString& csString::Replace unsigned long    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 414 of file csstring.h.

csString& csString::Replace long    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 413 of file csstring.h.

csString& csString::Replace unsigned int    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 412 of file csstring.h.

csString& csString::Replace int    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 411 of file csstring.h.

csString& csString::Replace unsigned short    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 410 of file csstring.h.

csString& csString::Replace short    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 409 of file csstring.h.

csString& csString::Replace unsigned char    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 408 of file csstring.h.

csString& csString::Replace char    s [inline]
 

Replace contents of this string with the value in formatted form.

Remarks:
Internally uses the various flavours of Append().

Definition at line 407 of file csstring.h.

csString& csString::Replace const char *    Str,
size_t    Count = (size_t)-1
 

Replace contents of this string with the contents of another.

Parameters:
Str  String from which new content of this string will be copied.
Count  Number of characters to copy. If (size_t)-1 is specified, then all characters will be copied.
Returns:
Reference to itself.
Remarks:
This string will represent a null-pointer after replacement if and only if Str is a null pointer.

csString& csString::Replace const csString &    Str,
size_t    Count = (size_t)-1
 

Replace contents of this string with the contents of another.

Parameters:
Str  String from which new content of this string will be copied.
Count  Number of characters to copy. If (size_t)-1 is specified, then all characters will be copied.
Returns:
Reference to itself.
Remarks:
This string will represent a null-pointer after replacement if and only if Str represents a null-pointer.

csString& csString::RTrim  
 

Trim trailing whitespace.

Returns:
Reference to itself.
Remarks:
This is equivalent to DeleteAt(0,n) where 'n' is the first non-whitespace character, or Lenght() if the string is composed entirely of whitespace.

void csString::SetAt size_t    n,
const char    c
[inline]
 

Set the n'th character.

Remarks:
The n'th character position must be a valid position in the string. You can not expand the string by setting a character beyond the end of string.

Definition at line 232 of file csstring.h.

void csString::SetCapacity size_t    NewSize
 

Advise the string that it should allocate enough space to hold up to NewSize characters.

Remarks:
After calling this method, the string's capacity will be at least NewSize + 1 (one for the implicit null terminator). Never shrinks capacity. If you need to actually reclaim memory, then use Free() or Reclaim().

void csString::SetGrowsBy size_t   
 

Advise the string that it should grow by approximately this many bytes when more space is required.

Remarks:
This value is only a suggestion. The actual value by which it grows may be rounded up or down to an implementation-dependent allocation multiple. This method turns off exponential growth.

void csString::SetGrowsExponentially bool    b [inline]
 

Tell the string to re-size its buffer exponentially as needed.

Remarks:
If set to true, the GetGrowsBy() setting is ignored.

Definition at line 109 of file csstring.h.

csString csString::Slice size_t    start,
size_t    len
const
 

Copy and return a portion of this string.

Parameters:
start  Start position of slice (zero-based).
len  Number of characters in slice.
Returns:
The indicated string slice.

void csString::SubString csString &    sub,
size_t    start,
size_t    len
const
 

Copy a portion of this string.

Parameters:
sub  Strign which will receive the indicated substring copy.
start  Start position of slice (zero-based).
len  Number of characters in slice.
Remarks:
Use this method instead of Slice() for cases where you expect to extract many substrings in a tight loop, and want to avoid the overhead of allocation of a new string object for each operation. Simply re-use 'sub' for each operation.

csString& csString::Trim  
 

Trim leading and trailing whitespace.

Returns:
Reference to itself.
Remarks:
This is equivalent to LTrim() followed by RTrim().

csString& csString::Truncate size_t    Len
 

Truncate the string.

Parameters:
Len  The number of characters to which the string should be truncated (possibly 0).
Returns:
Reference to itself.
Remarks:
Will only make a string shorter; will never extend it. This method does not reclaim memory; it merely shortens the string, which means that Truncate(0) is a handy method of clearing the string, without the overhead of slow heap management. This may be important if you want to re-use the same string many times over. If you need to reclaim memory after truncating the string, then invoke Reclaim(). GetData() and 'operator char const*' will return a non-null zero-length string if you truncate the string to 0 characters, unless the string had already represented a null-pointer, in which case it will continue to represent a null-pointer after truncation.

csString& csString::Upcase  
 

Convert this string to upper-case.

Returns:
Reference to itself.


The documentation for this class was generated from the following file:
Generated for Crystal Space by doxygen 1.2.18