Crystal Space: iString Struct Reference (Crystal Space Public API Reference)

| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# iString Struct Reference
[Utilities]

This is a SCF-compatible interface for csString. More...

`#include <iutil/string.h>`

Inheritance diagram for iString:

[legend]
List of all members.

## Public Member Functions
virtual void | Append (const iString *Str, size_t Count=(size_t)-1)=0
| Append a string to this one.
virtual void | Append (const char *Str, size_t Count=(size_t)-1)=0
| Append a null-terminated C-string to this one.
virtual void | Clear ()=0
| Clear the string (so that it contains only a null terminator).
virtual csRef< iString > | Clone () const =0
| Get a copy of this string.
virtual bool | Compare (const iString *Str) const =0
| Check if another string is equal to this one.
virtual bool | CompareNoCase (const iString *Str) const =0
| Check if another string is equal to this one.
virtual void | Downcase ()=0
| Convert string to lowercase.
virtual void | Empty ()=0
| Clear the string (so that it contains only a null terminator).
virtual size_t | Find (const char *search, size_t pos=0) const =0
| Find the first occurrence of `search` in this string starting at `pos`.
virtual size_t | FindFirst (const char c, size_t p=(size_t)-1) const =0
| Find the first occurrence of a character in the string.
virtual size_t | FindLast (const char c, size_t p=(size_t)-1) const =0
| Find the last occurrence of a character in the string.
virtual void | Format (const char *format,...)=0
| Format this string using sprintf()-style formatting directives.
virtual void | FormatV (const char *format, va_list args)=0
| Format this string using sprintf() formatting directives in a va_list.
virtual char | GetAt (size_t n) const =0
| Get the n'th character.
virtual size_t | GetCapacity () const =0
| Return the current capacity.
virtual char * | GetData ()=0
| Get a pointer to the null-terminated character array.
virtual char const * | GetData () const =0
| Get a pointer to the null-terminated character array.
virtual size_t | GetGrowsBy () const =0
| Return the number of bytes by which the string grows.
virtual void | Insert (size_t Pos, iString const *Str)=0
| Insert another string into this one.
virtual bool | IsEmpty () const =0
| Check if string is empty.
virtual size_t | Length () const =0
| Query string length.
virtual | operator char const * () const =0
| Get a pointer to the null-terminated character array.
virtual bool | operator!= (const iString &Str) const =0
| Check if another string is not equal to this one.
virtual csRef< iString > | operator+ (const iString &iStr) const =0
| Concatenate two strings and return a third one.
virtual void | operator+= (const char *iStr)=0
| Append a null-terminated C-string to this string.
virtual void | operator+= (const iString &iStr)=0
| Append another string to this one.
virtual bool | operator== (const iString &Str) const =0
| Check if another string is equal to this one.
virtual char | operator[] (size_t n) const =0
| Get n'th character.
virtual char & | operator[] (size_t n)=0
| Get a modifiable reference to n'th character.
virtual void | Overwrite (size_t Pos, iString const *Str)=0
| Overlay another string onto a part of this string.
virtual void | Reclaim ()=0
| Set string buffer capacity to hold exactly the current content.
virtual void | Replace (const char *str, size_t count=(size_t)-1)=0
| Replace contents of this string with the contents of another.
virtual void | Replace (const iString *str, size_t count=(size_t)-1)=0
| Replace contents of this string with the contents of another.
virtual void | ReplaceAll (const char *search, const char *replacement)=0
| Find all occurrences of `search` in this string and replace them with `replacement`.
virtual void | SetAt (size_t n, char iChar)=0
| Set the n'th character.
virtual void | SetCapacity (size_t NewSize)=0
| Advise the string that it should allocate enough space to hold up to NewSize characters.
virtual void | SetGrowsBy (size_t)=0
| Advise the string that it should grow its allocated buffer by approximately this many bytes when more space is required.
virtual void | ShrinkBestFit ()=0
| Set string buffer capacity to hold exactly the current content.
virtual csRef< iString > | Slice (size_t start, size_t len) const =0
| Copy and return a portion of this string.
virtual void | SubString (iString *sub, size_t start, size_t len) const =0
| Copy a portion of this string.
virtual void | Truncate (size_t Len)=0
| Truncate the string.
virtual void | Upcase ()=0
| Convert string to uppercase.

## Detailed Description

This is a SCF-compatible interface for csString.

Definition at line 32 of file string.h.

## Member Function Documentation

virtual void iString::Append | ( | const iString * | Str,
|  | size_t | Count = `(size_t)-1` |
| ) |  |  | `[pure virtual]`

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.

Implemented in scfString.

virtual void iString::Append | ( | const char * | Str,
|  | size_t | Count = `(size_t)-1` |
| ) |  |  | `[pure virtual]`

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.

Implemented in scfString.

virtual void iString::Clear | ( |  | ) | `[pure virtual]`

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

Remarks:
  This is typically shorthand for Truncate(0), but more idiomatic in terms of human language.

Deprecated:
  Use Empty() instead.

Implemented in scfString.

virtual csRef<iString> iString::Clone | ( |  | ) | const`[pure virtual]`

Get a copy of this string.

Implemented in scfString.

virtual bool iString::Compare | ( | const iString * | Str | ) | const`[pure virtual]`

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.

Implemented in scfString.

virtual bool iString::CompareNoCase | ( | const iString * | Str | ) | const`[pure virtual]`

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-insensitive.

Implemented in scfString.

virtual void iString::Downcase | ( |  | ) | `[pure virtual]`

Convert string to lowercase.

Implemented in scfString.

virtual void iString::Empty | ( |  | ) | `[pure virtual]`

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

Remarks:
  This is typically shorthand for Truncate(0), but more idiomatic in terms of human language.

Implemented in scfString.

virtual size_t iString::Find | ( | const char * | search,
|  | size_t | pos = `0` |
| ) |  |  | const`[pure virtual]`

Find the first occurrence of `search` in this string starting at `pos`.

Parameters:

  | search | String to locate.
  | pos | Start position of search (default 0).

Returns:
  First position of `search`, or (size_t)-1 if not found.

Implemented in scfString.

virtual size_t iString::FindFirst | ( | const char | c,
|  | size_t | p = `(size_t)-1` |
| ) |  |  | const`[pure virtual]`

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.

Implemented in scfString.

virtual size_t iString::FindLast | ( | const char | c,
|  | size_t | p = `(size_t)-1` |
| ) |  |  | const`[pure virtual]`

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.

Implemented in scfString.

virtual void iString::Format | ( | const char * | format,
|  |  | ... |
| ) |  |  | `[pure virtual]`

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

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

See also:
  Notes about string formatting in Crystal Space

Implemented in scfString.

virtual void iString::FormatV | ( | const char * | format,
|  | va_list | args |
| ) |  |  | `[pure virtual]`

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.

See also:
  Notes about string formatting in Crystal Space

Implemented in scfString.

virtual char iString::GetAt | ( | size_t | n | ) | const`[pure virtual]`

Get the n'th character.

Implemented in scfString.

virtual size_t iString::GetCapacity | ( |  | ) | const`[pure virtual]`

Return the current capacity.

Implemented in scfString.

virtual char* iString::GetData | ( |  | ) | `[pure virtual]`

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.

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

Deprecated:
  Use the 'const' version of GetData() instead.

Implemented in scfString.

virtual char const* iString::GetData | ( |  | ) | const`[pure virtual]`

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.

Implemented in scfString.

virtual size_t iString::GetGrowsBy | ( |  | ) | const`[pure virtual]`

Return the number of bytes by which the string grows.

Remarks:
  If the return value is zero, then the internal buffer grows exponentially by doubling its size, rather than by fixed increments.

Implemented in scfString.

virtual void iString::Insert | ( | size_t | Pos,
|  | iString const * | Str |
| ) |  |  | `[pure virtual]`

Insert another string into this one.

Parameters:

  | Pos | Position at which to insert the other string (zero-based).
  | Str | String to insert.

Implemented in scfString.

virtual bool iString::IsEmpty | ( |  | ) | const`[pure virtual]`

Check if string is empty.

Returns:
  True if the string is empty; false if it is not.

Remarks:
  This is equivalent to the expression 'Length() == 0'.

Implemented in scfString.

virtual size_t iString::Length | ( |  | ) | const`[pure virtual]`

Query string length.

Returns:
  The string length.

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

Implemented in scfString.

virtual iString::operator char const * | ( |  | ) | const`[pure virtual]`

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.

Implemented in scfString.

virtual bool iString::operator!= | ( | const iString & | Str | ) | const`[pure virtual]`

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.

Implemented in scfString.

virtual csRef<iString> iString::operator+ | ( | const iString & | iStr | ) | const`[pure virtual]`

Concatenate two strings and return a third one.

Implemented in scfString.

virtual void iString::operator+= | ( | const char * | iStr | ) | `[pure virtual]`

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

Implemented in scfString.

virtual void iString::operator+= | ( | const iString & | iStr | ) | `[pure virtual]`

Append another string to this one.

Implemented in scfString.

virtual bool iString::operator== | ( | const iString & | Str | ) | const`[pure virtual]`

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.

Implemented in scfString.

virtual char iString::operator[] | ( | size_t | n | ) | const`[pure virtual]`

Get n'th character.

Implemented in scfString.

virtual char& iString::operator[] | ( | size_t | n | ) | `[pure virtual]`

Get a modifiable reference to n'th character.

Implemented in scfString.

virtual void iString::Overwrite | ( | size_t | Pos,
|  | iString const * | Str |
| ) |  |  | `[pure virtual]`

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.

Remarks:
  The target string will grow as necessary to accept the new string.

Implemented in scfString.

virtual void iString::Reclaim | ( |  | ) | `[pure virtual]`

Set string buffer capacity to hold exactly the current content.

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 the implementation may shrink the allocation so that it only holds the implicit null terminator, or it may free the string's memory completely.

Deprecated:
  Use ShrinkBestFit() instead.

Implemented in scfString.

virtual void iString::Replace | ( | const char * | str,
|  | size_t | count = `(size_t)-1` |
| ) |  |  | `[pure virtual]`

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.

Implemented in scfString.

virtual void iString::Replace | ( | const iString * | str,
|  | size_t | count = `(size_t)-1` |
| ) |  |  | `[pure virtual]`

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.

Implemented in scfString.

virtual void iString::ReplaceAll | ( | const char * | search,
|  | const char * | replacement |
| ) |  |  | `[pure virtual]`

Find all occurrences of `search` in this string and replace them with `replacement`.

Implemented in scfString.

virtual void iString::SetAt | ( | size_t | n,
|  | char | iChar |
| ) |  |  | `[pure virtual]`

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.

Implemented in scfString.

virtual void iString::SetCapacity | ( | size_t | NewSize | ) | `[pure virtual]`

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

Implemented in scfString.

virtual void iString::SetGrowsBy | ( | size_t |  | ) | `[pure virtual]`

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

This is an optimization to avoid excessive memory reallocation and heap management, which can be quite slow.

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.

  If the value is zero, then the internal buffer grows exponentially by doubling its size, rather than by fixed increments.

Implemented in scfString.

virtual void iString::ShrinkBestFit | ( |  | ) | `[pure virtual]`

Set string buffer capacity to hold exactly the current content.

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 the implementation may shrink the allocation so that it only holds the implicit null terminator, or it may free the string's memory completely.

Implemented in scfString.

virtual csRef<iString> iString::Slice | ( | size_t | start,
|  | size_t | len |
| ) |  |  | const`[pure virtual]`

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.

Implemented in scfString.

virtual void iString::SubString | ( | iString * | sub,
|  | size_t | start,
|  | size_t | len |
| ) |  |  | const`[pure virtual]`

Copy a portion of this string.

Parameters:

  | sub | String 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.

Implemented in scfString.

virtual void iString::Truncate | ( | size_t | Len | ) | `[pure virtual]`

Truncate the string.

Parameters:

  | Len | The number of characters to which the string should be truncated (possibly 0).

Remarks:
  Will only make a string shorter; will never extend it. This method may or may not reclaim memory depending upon the implementation. If you positively need to reclaim memory after truncating the string, then invoke Reclaim().

Implemented in scfString.

virtual void iString::Upcase | ( |  | ) | `[pure virtual]`

Convert string to uppercase.

Implemented in scfString.

The documentation for this struct was generated from the following file:

- iutil/string.h