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