CrystalSpace

Public API Reference

iString Struct Reference
[Utilities]

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

#include <iutil/string.h>

Inheritance diagram for iString:

Inheritance graph
[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< iStringClone () 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< iStringoperator+ (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< iStringSlice (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:
Generated for Crystal Space 1.0.2 by doxygen 1.4.7