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 typesafe 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 to length Len. Returns a reference to itself.

csString & Reclaim ()
 Set string buffer capacity to exactly hold 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.

size_t Length () const
 Query string length. Length does not include null terminator.

bool IsEmpty () const
 Check if string is empty.

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

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

void SetAt (size_t n, const char c)
 Set character at position `n'.

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

csString & DeleteAt (size_t Pos, size_t Count=1)
 Delete Count characters at starting Pos. Returns a reference to itself.

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

csString & Insert (size_t iPos, const char *)
 Insert another string into this one at position iPos.

csString & Insert (size_t Pos, const char)
 Insert a character into this string at position Pos.

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

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

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

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

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 first character 'c' from position 'p'.

size_t FindLast (char c, size_t p=(size_t)-1) const
 Find last character 'c', counting backwards from position 'p'.

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 two strings are equal.

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

bool CompareNoCase (const csString &iStr) const
 Compare two strings ignoring case.

bool CompareNoCase (const char *iStr) const
 Compare ignoring case with a null-terminated 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 a csString object.

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

csString & LTrim ()
 Trim leading whitespace. Returns a reference to itself.

csString & RTrim ()
 Trim trailing whitespace. Returns a reference to itself.

csString & Trim ()
 Trim leading and trailing whitespace. Returns a reference to itself.

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() 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 iNewSize, char iChar=' ')
 Pad to a specified size with leading characters (default: space).

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

csString & PadRight (size_t iNewSize, char iChar=' ')
 Pad to a specified size with trailing characters (default: space).

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

csString & PadCenter (size_t iNewSize, char iChar=' ')
 Pad to a specified size between characters (any remainder is appended).

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

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

 operator const char * () const
 Return a pointer to the null-terminated character string.

bool operator== (const csString &iStr) const
 Check if two strings are equal.

bool operator== (const char *iStr) const
 Check if two strings are equal.

bool operator!= (const csString &iStr) const
 Check if two strings are not equal.

bool operator!= (const char *iStr) const
 Check if two strings are not equal.

csString & Downcase ()
 Convert the string to lower-case. Returns a reference to itself.

csString & Upcase ()
 Convert the string to upper-case. Returns a reference to itself.

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


Detailed Description

This is a string class with a range of useful operators and typesafe overloads.

May contain arbitary binary data, including null bytes. 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().

Definition at line 34 of file csstring.h.


Constructor & Destructor Documentation

csString::csString   [inline]
 

Create an empty csString object.

Definition at line 336 of file csstring.h.

Referenced by Clone().

csString::csString size_t    Length [inline]
 

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

Definition at line 343 of file csstring.h.

References Length(), and SetCapacity().

csString::csString const csString &    copy [inline]
 

Copy constructor.

Definition at line 348 of file csstring.h.

References Append().

csString::csString const char *    src [inline]
 

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

Definition at line 353 of file csstring.h.

References Append().

csString::csString char    c [inline]
 

Create a csString object from a single signed character.

Definition at line 358 of file csstring.h.

References Append().

csString::csString unsigned char    c [inline]
 

Create a csString object from a single unsigned character.

Definition at line 363 of file csstring.h.

References Append().

virtual csString::~csString   [virtual]
 

Destroy a csString object.


Member Function Documentation

csString& csString::Append bool    b [inline]
 

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

Definition at line 259 of file csstring.h.

References Append().

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

Append an unsigned character to this string.

Returns a reference to itself.

Definition at line 213 of file csstring.h.

References Append().

csString& csString::Append char    c [inline]
 

Append a signed character to this string. Returns a reference to itself.

Definition at line 206 of file csstring.h.

References Append().

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

Append a string to this one.

If Count is -1, then the entire string is appended. Otherwise, only Count characters from the string are appended. Returns a reference to itself.

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

Append a null-terminated string to this one.

If Count is -1, then the entire string is appended. Otherwise, only Count characters from the string are appended. Returns a reference to itself.

Referenced by Append(), csString(), operator+(), and Replace().

csString csString::AsPadCenter size_t    iNewSize,
char    iChar = ' '
const
 

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

csString csString::AsPadLeft size_t    iNewSize,
char    iChar = ' '
const
 

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

csString csString::AsPadRight size_t    iNewSize,
char    iChar = ' '
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 a reference to itself.

Definition at line 111 of file csstring.h.

References Truncate().

csString csString::Clone   const [inline]
 

Get a copy of this string.

Definition at line 371 of file csstring.h.

References csString().

Referenced by operator+().

csString& csString::Collapse  
 

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

Returns a reference to itself.

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

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

Definition at line 315 of file csstring.h.

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

Check if two strings are equal.

Definition at line 302 of file csstring.h.

References GetData(), and Length().

Referenced by operator!=(), and operator==().

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

Compare ignoring case with a null-terminated string.

Definition at line 332 of file csstring.h.

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

Compare two strings ignoring case.

Definition at line 319 of file csstring.h.

References GetData(), and Length().

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

Delete Count characters at starting Pos. Returns a reference to itself.

char* csString::Detach   [inline]
 

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

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. The returned value may be 0 if no buffer had been allocated for this string.

Definition at line 589 of file csstring.h.

csString& csString::Downcase  
 

Convert the string to lower-case. Returns a reference to itself.

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

Find first character 'c' from position 'p'.

If the character cannot be found, this function returns (size_t)-1

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

Find last character 'c', counting backwards from position 'p'.

Default position is the end of the string. If the character cannot be found, this function returns (size_t)-1

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

Format this string using sprintf() formatting directives.

Automatically allocates sufficient memory to hold result. Newly formatted string overwrites previous string value. Returns a reference to itself.

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

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

Automatically allocates sufficient memory to hold result. Newly formatted string overwrites previous string value. Returns a reference to itself.

void csString::Free  
 

Free the memory allocated for the string.

char csString::GetAt size_t    n const [inline]
 

Get character at n'th position.

Definition at line 158 of file csstring.h.

size_t csString::GetCapacity   const [inline]
 

Return the current capacity.

Definition at line 68 of file csstring.h.

char* csString::GetData   [inline]
 

Get a pointer to the null-terminated character array.

Warning: this is a non-const pointer, so use this function with care!

Definition at line 122 of file csstring.h.

char const* csString::GetData   const [inline]
 

Get a pointer to the null-terminated character array.

Definition at line 115 of file csstring.h.

Referenced by Compare(), and CompareNoCase().

size_t csString::GetGrowsBy   const [inline]
 

Return the number of bytes by which the string grows.

Definition at line 81 of file csstring.h.

bool csString::GetGrowsExponentially   const [inline]
 

Returns true if exponential growth is enabled.

Definition at line 92 of file csstring.h.

csString& csString::Insert size_t    Pos,
const    char
 

Insert a character into this string at position Pos.

Returns a reference to itself.

csString& csString::Insert size_t    iPos,
const char *   
 

Insert another string into this one at position iPos.

Returns a reference to itself.

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

Insert another string into this one at position Pos.

Returns a reference to itself.

bool csString::IsEmpty   const [inline]
 

Check if string is empty.

Definition at line 130 of file csstring.h.

size_t csString::Length   const [inline]
 

Query string length. Length does not include null terminator.

Definition at line 126 of file csstring.h.

Referenced by Compare(), CompareNoCase(), and csString().

csString& csString::LTrim  
 

Trim leading whitespace. Returns a reference to itself.

csString::operator const char *   const [inline]
 

Return a pointer to the null-terminated character string.

Definition at line 561 of file csstring.h.

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

Check if two strings are not equal.

Definition at line 574 of file csstring.h.

References Compare().

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

Check if two strings are not equal.

Definition at line 571 of file csstring.h.

References Compare().

const 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 557 of file csstring.h.

References Append(), and Clone().

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

Check if two strings are equal.

Definition at line 568 of file csstring.h.

References Compare().

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

Check if two strings are equal.

Definition at line 565 of file csstring.h.

References Compare().

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

Get n'th character.

Definition at line 141 of file csstring.h.

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

Get a reference to n'th character.

Definition at line 134 of file csstring.h.

csString& csString::Overwrite size_t    iPos,
const csString &   
 

Overlay another string onto a part of this string.

Returns a reference to itself.

csString& csString::PadCenter size_t    iNewSize,
char    iChar = ' '
 

Pad to a specified size between characters (any remainder is appended).

Returns a reference to itself.

csString& csString::PadLeft size_t    iNewSize,
char    iChar = ' '
 

Pad to a specified size with leading characters (default: space).

Returns a reference to itself.

csString& csString::PadRight size_t    iNewSize,
char    iChar = ' '
 

Pad to a specified size with trailing characters (default: space).

Returns a reference to itself.

csString& csString::Reclaim  
 

Set string buffer capacity to exactly hold the current content.

Returns a reference to itself.

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

Replace contents of this string with the contents of another.

If Count is -1, then use the entire replacement string. Otherwise, use Count characters from the replacement string. Returns a reference to itself.

Definition at line 278 of file csstring.h.

References Append().

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

Replace contents of this string with the contents of another.

If Count is -1, then use the entire replacement string. Otherwise, use Count characters from the replacement string. Returns a reference to itself.

Definition at line 267 of file csstring.h.

References Append().

csString& csString::RTrim  
 

Trim trailing whitespace. Returns a reference to itself.

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

Set character at position `n'.

Does not expand string if `n' is greater than length of string.

Definition at line 151 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.

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().

Referenced by csString().

void csString::SetGrowsBy size_t   
 

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

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.

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

Definition at line 88 of file csstring.h.

csString csString::Slice size_t    start,
size_t    len
const
 

Copy and return a portion of this string.

The substring runs from `start' for `len' characters.

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

Copy a portion of this string.

The result is placed in `sub'. The substring runs from `start' for `len' characters. 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 for each operation. You can keep passing in the same `sub' for each invocation, thus avoiding creation of a new string object.

csString& csString::Trim  
 

Trim leading and trailing whitespace. Returns a reference to itself.

csString& csString::Truncate size_t    Len
 

Truncate the string to length Len. Returns a reference to itself.

Referenced by Clear().

csString& csString::Upcase  
 

Convert the string to upper-case. Returns a reference to itself.


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