ResidualVM logo ResidualVM website - Forums - Contact us BuildBot - Doxygen - Wiki curved edge

Simple string class for ScummVM. More...

#include <str.h>

List of all members.

Public Types

typedef char value_type
typedef unsigned char unsigned_type
 Unsigned version of the underlying type.
typedef char * iterator
typedef const char * const_iterator

Public Member Functions

 String ()
 Construct a new empty string.
 String (const char *str)
 Construct a new string from the given NULL-terminated C string.
 String (const char *str, uint32 len)
 Construct a new string containing exactly len characters read from address str.
 String (const char *beginP, const char *endP)
 Construct a new string containing the characters between beginP (including) and endP (excluding).
 String (const String &str)
 Construct a copy of the given string.
 String (char c)
 Construct a string consisting of the given character.
 String (const U32String &str)
 Construct a new string from the given u32 string.
 ~String ()
Stringoperator= (const char *str)
Stringoperator= (const String &str)
Stringoperator= (char c)
Stringoperator+= (const char *str)
Stringoperator+= (const String &str)
Stringoperator+= (char c)
bool operator== (const String &x) const
bool operator== (const char *x) const
bool operator!= (const String &x) const
bool operator!= (const char *x) const
bool operator< (const String &x) const
bool operator<= (const String &x) const
bool operator> (const String &x) const
bool operator>= (const String &x) const
bool equals (const String &x) const
bool equalsIgnoreCase (const String &x) const
int compareTo (const String &x) const
int compareToIgnoreCase (const String &x) const
bool equals (const char *x) const
bool equalsIgnoreCase (const char *x) const
int compareTo (const char *x) const
int compareToIgnoreCase (const char *x) const
int compareDictionary (const String &x) const
int compareDictionary (const char *x) const
bool hasSuffix (const String &x) const
bool hasSuffix (const char *x) const
bool hasSuffixIgnoreCase (const String &x) const
bool hasSuffixIgnoreCase (const char *x) const
bool hasPrefix (const String &x) const
bool hasPrefix (const char *x) const
bool hasPrefixIgnoreCase (const String &x) const
bool hasPrefixIgnoreCase (const char *x) const
bool contains (const String &x) const
bool contains (const char *x) const
bool contains (char x) const
bool contains (uint32 x) const
uint64 asUint64 () const
 Return uint64 corrensponding to String's contents.
bool matchString (const char *pat, bool ignoreCase=false, bool pathMode=false) const
 Simple DOS-style pattern matching function (understands * and ? like used in DOS).
bool matchString (const String &pat, bool ignoreCase=false, bool pathMode=false) const
const char * c_str () const
uint size () const
bool empty () const
char firstChar () const
char lastChar () const
char operator[] (int idx) const
void deleteLastChar ()
 Remove the last character from the string.
void deleteChar (uint32 p)
 Remove the character at position p from the string.
void erase (uint32 p, uint32 len=npos)
 Remove all characters from position p to the p + len.
iterator erase (iterator it)
 Erases the character at the given iterator location.
void setChar (char c, uint32 p)
 Set character c at position p, replacing the previous character there.
void insertChar (char c, uint32 p)
 Insert character c before position p.
void clear ()
 Clears the string, making it empty.
void toLowercase ()
 Convert all characters in the string to lowercase.
void toUppercase ()
 Convert all characters in the string to uppercase.
void trim ()
 Removes trailing and leading whitespaces.
void wordWrap (const uint32 maxLength)
 Wraps the text in the string to the given line maximum.
uint hash () const
size_t find (char c, size_t pos=0) const
 Finds the index of a character in the string.
size_t find (const char *s) const
 Does a find for the passed string.
uint32 find (const String &str, uint32 pos=0) const
size_t rfind (const char *s) const
 Does a reverse find for the passed string.
size_t rfind (const String &s) const
size_t rfind (char c, size_t pos=npos) const
 Does a reverse find for a passed character.
size_t findFirstOf (char c, size_t pos=0) const
 Find first character in the string matching the passed character.
size_t findFirstOf (const char *chars, size_t pos=0) const
 Find first character in the string that's any character of the passed string.
size_t findFirstOf (const String &chars, size_t pos=0) const
size_t findLastOf (char c, size_t pos=npos) const
 Find the last character in the string that's the specified character.
size_t findLastOf (const char *chars, size_t pos=npos) const
 Find the last character in the string that's in any of the passed characters.
size_t findLastOf (const String &chars, size_t pos=npos) const
size_t findFirstNotOf (char c, size_t pos=0) const
 Find first character in the string that's not the specified character.
size_t findFirstNotOf (const char *chars, size_t pos=0) const
 Find first character in the string that's not any character of the passed string.
size_t findFirstNotOf (const String &chars, size_t pos=0) const
size_t findLastNotOf (char c) const
 Find the last character in the string that's not the specified character.
size_t findLastNotOf (const char *chars) const
 Find the last character in the string that's not in any of the passed characters.
size_t findLastNotOf (const String &chars) const
String substr (size_t pos=0, size_t len=npos) const
 Return a substring of this string.
iterator begin ()
iterator end ()
const_iterator begin () const
const_iterator end () const
U32String decode (CodePage page=kUtf8) const
 Python-like method.

void replace (uint32 pos, uint32 count, const String &str)
void replace (uint32 pos, uint32 count, const char *str)
void replace (iterator begin, iterator end, const String &str)
void replace (iterator begin, iterator end, const char *str)
void replace (uint32 posOri, uint32 countOri, const String &str, uint32 posDest, uint32 countDest)
void replace (uint32 posOri, uint32 countOri, const char *str, uint32 posDest, uint32 countDest)

Static Public Member Functions

static void releaseMemoryPoolMutex ()
static String format (const char *fmt,...) GCC_PRINTF(1
 Print formatted data into a String object.
static String static String vformat (const char *fmt, va_list args)
 Print formatted data into a String object.

Static Public Attributes

static const uint32 npos = 0xFFFFFFFF

Protected Member Functions

bool isStorageIntern () const
void makeUnique ()
void ensureCapacity (uint32 new_size, bool keep_old)
 Ensure that enough storage is available to store at least new_size characters plus a null byte.
void incRefCount () const
void decRefCount (int *oldRefCount)
void initWithCStr (const char *str, uint32 len)
bool pointerInOwnBuffer (const char *str) const
void decodeUTF8 (U32String &dst) const
void decodeOneByte (U32String &dst, CodePage page) const

Protected Attributes

uint32 _size
 Length of the string.
char * _str
 Pointer to the actual string storage.
union {
   char   _storage [_builtinCapacity]
 Internal string storage.
   struct {
      int *   _refCount
      uint32   _capacity
   }   _extern
 External string storage data -- the refcounter, and the capacity of the string _str points to.
}; 

Static Protected Attributes

static const uint32 _builtinCapacity = 32 - sizeof(uint32) - sizeof(char *)
 The size of the internal storage.

Detailed Description

Simple string class for ScummVM.

Provides automatic storage managment, and overloads several operators in a 'natural' fashion, mimicking the std::string class. Even provides simple iterators.

This class tries to avoid allocating lots of small blocks on the heap, since that is inefficient on several platforms supported by ScummVM. Instead, small strings are stored 'inside' the string object (i.e. on the stack, for stack allocated objects), and only for strings exceeding a certain length do we allocate a buffer on the heap.

The presence of characters in the string will cause undefined behavior in some operations.

Definition at line 50 of file str.h.


Member Typedef Documentation

typedef const char* Common::String::const_iterator

Definition at line 64 of file str.h.

typedef char* Common::String::iterator

Definition at line 63 of file str.h.

typedef unsigned char Common::String::unsigned_type

Unsigned version of the underlying type.

This can be used to cast individual string characters to bigger integer types without sign extension happening.

Definition at line 62 of file str.h.

Definition at line 56 of file str.h.


Constructor & Destructor Documentation

Common::String::String (  )  [inline]

Construct a new empty string.

Definition at line 115 of file str.h.

Common::String::String ( const char *  str  ) 

Construct a new string from the given NULL-terminated C string.

Definition at line 64 of file str.cpp.

Common::String::String ( const char *  str,
uint32  len 
)

Construct a new string containing exactly len characters read from address str.

Definition at line 72 of file str.cpp.

Common::String::String ( const char *  beginP,
const char *  endP 
)

Construct a new string containing the characters between beginP (including) and endP (excluding).

Definition at line 76 of file str.cpp.

Common::String::String ( const String str  ) 

Construct a copy of the given string.

Definition at line 103 of file str.cpp.

Common::String::String ( char  c  )  [explicit]

Construct a string consisting of the given character.

Definition at line 119 of file str.cpp.

Common::String::String ( const U32String str  ) 

Construct a new string from the given u32 string.

Definition at line 128 of file str.cpp.

Common::String::~String (  ) 

Definition at line 134 of file str.cpp.


Member Function Documentation

uint64 Common::String::asUint64 (  )  const

Return uint64 corrensponding to String's contents.

Definition at line 435 of file str.cpp.

iterator Common::String::begin (  )  [inline]

Definition at line 374 of file str.h.

const_iterator Common::String::begin (  )  const [inline]

Definition at line 388 of file str.h.

const char* Common::String::c_str (  )  const [inline]

Definition at line 213 of file str.h.

void Common::String::clear (  ) 

Clears the string, making it empty.

Definition at line 492 of file str.cpp.

int Common::String::compareDictionary ( const String x  )  const

Definition at line 928 of file str.cpp.

int Common::String::compareDictionary ( const char *  x  )  const

Definition at line 932 of file str.cpp.

int Common::String::compareTo ( const char *  x  )  const

Definition at line 914 of file str.cpp.

int Common::String::compareTo ( const String x  )  const

Definition at line 910 of file str.cpp.

int Common::String::compareToIgnoreCase ( const String x  )  const

Definition at line 919 of file str.cpp.

int Common::String::compareToIgnoreCase ( const char *  x  )  const

Definition at line 923 of file str.cpp.

bool Common::String::contains ( const String x  )  const

Definition at line 413 of file str.cpp.

bool Common::String::contains ( char  x  )  const

Definition at line 422 of file str.cpp.

bool Common::String::contains ( const char *  x  )  const

Definition at line 417 of file str.cpp.

bool Common::String::contains ( uint32  x  )  const

Definition at line 426 of file str.cpp.

U32String Common::String::decode ( CodePage  page = kUtf8  )  const

Python-like method.

Definition at line 343 of file str-enc.cpp.

void Common::String::decodeOneByte ( U32String dst,
CodePage  page 
) const [protected]

Definition at line 303 of file str-enc.cpp.

void Common::String::decodeUTF8 ( U32String dst  )  const [protected]

Definition at line 39 of file str-enc.cpp.

void Common::String::decRefCount ( int *  oldRefCount  )  [protected]

Definition at line 222 of file str.cpp.

void Common::String::deleteChar ( uint32  p  ) 

Remove the character at position p from the string.

Definition at line 457 of file str.cpp.

void Common::String::deleteLastChar (  ) 

Remove the last character from the string.

Definition at line 452 of file str.cpp.

bool Common::String::empty (  )  const [inline]

Definition at line 216 of file str.h.

const_iterator Common::String::end (  )  const [inline]

Definition at line 392 of file str.h.

iterator Common::String::end (  )  [inline]

Definition at line 384 of file str.h.

void Common::String::ensureCapacity ( uint32  new_size,
bool  keep_old 
) [protected]

Ensure that enough storage is available to store at least new_size characters plus a null byte.

In addition, if we currently share the storage with another string, unshare it, so that we can safely write to the storage.

Definition at line 148 of file str.cpp.

bool Common::String::equals ( const String x  )  const

Definition at line 892 of file str.cpp.

bool Common::String::equals ( const char *  x  )  const

Definition at line 896 of file str.cpp.

bool Common::String::equalsIgnoreCase ( const String x  )  const

Definition at line 901 of file str.cpp.

bool Common::String::equalsIgnoreCase ( const char *  x  )  const

Definition at line 905 of file str.cpp.

void Common::String::erase ( uint32  p,
uint32  len = npos 
)

Remove all characters from position p to the p + len.

If len = String::npos, removes all characters to the end

Definition at line 466 of file str.cpp.

String::iterator Common::String::erase ( iterator  it  ) 

Erases the character at the given iterator location.

Definition at line 487 of file str.cpp.

size_t Common::String::find ( char  c,
size_t  pos = 0 
) const

Finds the index of a character in the string.

Definition at line 735 of file str.cpp.

size_t Common::String::find ( const char *  s  )  const

Does a find for the passed string.

Definition at line 740 of file str.cpp.

uint32 Common::String::find ( const String str,
uint32  pos = 0 
) const

Definition at line 645 of file str.cpp.

size_t Common::String::findFirstNotOf ( char  c,
size_t  pos = 0 
) const

Find first character in the string that's not the specified character.

Definition at line 799 of file str.cpp.

size_t Common::String::findFirstNotOf ( const char *  chars,
size_t  pos = 0 
) const

Find first character in the string that's not any character of the passed string.

Definition at line 808 of file str.cpp.

size_t Common::String::findFirstNotOf ( const String chars,
size_t  pos = 0 
) const [inline]

Definition at line 356 of file str.h.

size_t Common::String::findFirstOf ( char  c,
size_t  pos = 0 
) const

Find first character in the string matching the passed character.

Definition at line 765 of file str.cpp.

size_t Common::String::findFirstOf ( const char *  chars,
size_t  pos = 0 
) const

Find first character in the string that's any character of the passed string.

Definition at line 770 of file str.cpp.

size_t Common::String::findFirstOf ( const String chars,
size_t  pos = 0 
) const [inline]

Definition at line 338 of file str.h.

size_t Common::String::findLastNotOf ( const char *  chars  )  const

Find the last character in the string that's not in any of the passed characters.

Definition at line 826 of file str.cpp.

size_t Common::String::findLastNotOf ( const String chars  )  const [inline]

Definition at line 365 of file str.h.

size_t Common::String::findLastNotOf ( char  c  )  const

Find the last character in the string that's not the specified character.

Definition at line 817 of file str.cpp.

size_t Common::String::findLastOf ( const String chars,
size_t  pos = npos 
) const [inline]

Definition at line 347 of file str.h.

size_t Common::String::findLastOf ( char  c,
size_t  pos = npos 
) const

Find the last character in the string that's the specified character.

Definition at line 779 of file str.cpp.

size_t Common::String::findLastOf ( const char *  chars,
size_t  pos = npos 
) const

Find the last character in the string that's in any of the passed characters.

Definition at line 789 of file str.cpp.

char Common::String::firstChar (  )  const [inline]

Definition at line 217 of file str.h.

String Common::String::format ( const char *  fmt,
  ... 
) [static]

Print formatted data into a String object.

Similar to sprintf, except that it stores the result in (variably sized) String instead of a fixed size buffer.

Definition at line 671 of file str.cpp.

uint Common::String::hash (  )  const

Definition at line 589 of file str.cpp.

bool Common::String::hasPrefix ( const char *  x  )  const

Definition at line 343 of file str.cpp.

bool Common::String::hasPrefix ( const String x  )  const

Definition at line 339 of file str.cpp.

bool Common::String::hasPrefixIgnoreCase ( const String x  )  const

Definition at line 356 of file str.cpp.

bool Common::String::hasPrefixIgnoreCase ( const char *  x  )  const

Definition at line 360 of file str.cpp.

bool Common::String::hasSuffix ( const String x  )  const

Definition at line 373 of file str.cpp.

bool Common::String::hasSuffix ( const char *  x  )  const

Definition at line 377 of file str.cpp.

bool Common::String::hasSuffixIgnoreCase ( const String x  )  const

Definition at line 393 of file str.cpp.

bool Common::String::hasSuffixIgnoreCase ( const char *  x  )  const

Definition at line 397 of file str.cpp.

void Common::String::incRefCount (  )  const [protected]

Definition at line 205 of file str.cpp.

void Common::String::initWithCStr ( const char *  str,
uint32  len 
) [protected]

Definition at line 81 of file str.cpp.

void Common::String::insertChar ( char  c,
uint32  p 
)

Insert character c before position p.

Definition at line 507 of file str.cpp.

bool Common::String::isStorageIntern (  )  const [inline, protected]

Definition at line 109 of file str.h.

char Common::String::lastChar (  )  const [inline]

Definition at line 218 of file str.h.

void Common::String::makeUnique (  )  [protected]

Definition at line 138 of file str.cpp.

bool Common::String::matchString ( const String pat,
bool  ignoreCase = false,
bool  pathMode = false 
) const

Definition at line 448 of file str.cpp.

bool Common::String::matchString ( const char *  pat,
bool  ignoreCase = false,
bool  pathMode = false 
) const

Simple DOS-style pattern matching function (understands * and ? like used in DOS).

Taken from exult/files/listfiles.cc

Token meaning: "*": any character, any amount of times. "?": any character, only once. "#": any decimal digit, only once. "\#": #, only once.

Example strings/patterns: String: monkey.s01 Pattern: monkey.s?? => true String: monkey.s101 Pattern: monkey.s?? => false String: monkey.s99 Pattern: monkey.s?1 => false String: monkey.s101 Pattern: monkey.s* => true String: monkey.s99 Pattern: monkey.s*1 => false String: monkey.s01 Pattern: monkey.s## => true String: monkey.s01 Pattern: monkey.### => false

Parameters:
pat Glob pattern.
ignoreCase Whether to ignore the case when doing pattern match
pathMode Whether to use path mode, i.e., whether slashes must be matched explicitly.
Returns:
true if str matches the pattern, false otherwise.

Definition at line 444 of file str.cpp.

bool Common::String::operator!= ( const String x  )  const

Definition at line 855 of file str.cpp.

bool Common::String::operator!= ( const char *  x  )  const

Definition at line 859 of file str.cpp.

String & Common::String::operator+= ( const char *  str  ) 

Definition at line 292 of file str.cpp.

String & Common::String::operator+= ( char  c  ) 

Definition at line 330 of file str.cpp.

String & Common::String::operator+= ( const String str  ) 

Definition at line 316 of file str.cpp.

bool Common::String::operator< ( const String x  )  const

Definition at line 864 of file str.cpp.

bool Common::String::operator<= ( const String x  )  const

Definition at line 868 of file str.cpp.

String & Common::String::operator= ( const String str  ) 

Definition at line 259 of file str.cpp.

String & Common::String::operator= ( char  c  ) 

Definition at line 281 of file str.cpp.

String & Common::String::operator= ( const char *  str  ) 

Definition at line 251 of file str.cpp.

bool Common::String::operator== ( const String x  )  const

Definition at line 846 of file str.cpp.

bool Common::String::operator== ( const char *  x  )  const

Definition at line 850 of file str.cpp.

bool Common::String::operator> ( const String x  )  const

Definition at line 872 of file str.cpp.

bool Common::String::operator>= ( const String x  )  const

Definition at line 876 of file str.cpp.

char Common::String::operator[] ( int  idx  )  const [inline]

Definition at line 220 of file str.h.

bool Common::String::pointerInOwnBuffer ( const char *  str  )  const [protected]

Definition at line 306 of file str.cpp.

void Common::String::releaseMemoryPoolMutex (  )  [static]

Definition at line 52 of file str.cpp.

void Common::String::replace ( uint32  posOri,
uint32  countOri,
const String str,
uint32  posDest,
uint32  countDest 
)

Definition at line 609 of file str.cpp.

void Common::String::replace ( iterator  begin,
iterator  end,
const String str 
)

Definition at line 601 of file str.cpp.

void Common::String::replace ( uint32  pos,
uint32  count,
const char *  str 
)

Definition at line 597 of file str.cpp.

void Common::String::replace ( uint32  pos,
uint32  count,
const String str 
)

Functions to replace some amount of chars with chars from some other string.

Note:
The implementation follows that of the STL's std::string: http://www.cplusplus.com/reference/string/string/replace/
Parameters:
pos Starting position for the replace in the original string.
count Number of chars to replace from the original string.
str Source of the new chars.
posOri Same as pos
countOri Same as count
posDest Initial position to read str from.
countDest Number of chars to read from str. npos by default.

Definition at line 593 of file str.cpp.

void Common::String::replace ( iterator  begin,
iterator  end,
const char *  str 
)

Definition at line 605 of file str.cpp.

void Common::String::replace ( uint32  posOri,
uint32  countOri,
const char *  str,
uint32  posDest,
uint32  countDest 
)

< Offset to copy the characters

< Number of positions that we have to pull back

Definition at line 614 of file str.cpp.

size_t Common::String::rfind ( char  c,
size_t  pos = npos 
) const

Does a reverse find for a passed character.

Definition at line 756 of file str.cpp.

size_t Common::String::rfind ( const char *  s  )  const

Does a reverse find for the passed string.

Definition at line 745 of file str.cpp.

size_t Common::String::rfind ( const String s  )  const [inline]

Definition at line 326 of file str.h.

void Common::String::setChar ( char  c,
uint32  p 
)

Set character c at position p, replacing the previous character there.

Definition at line 500 of file str.cpp.

uint Common::String::size (  )  const [inline]

Definition at line 214 of file str.h.

String Common::String::substr ( size_t  pos = 0,
size_t  len = npos 
) const

Return a substring of this string.

Definition at line 835 of file str.cpp.

void Common::String::toLowercase (  ) 

Convert all characters in the string to lowercase.

Definition at line 517 of file str.cpp.

void Common::String::toUppercase (  ) 

Convert all characters in the string to uppercase.

Definition at line 523 of file str.cpp.

void Common::String::trim (  ) 

Removes trailing and leading whitespaces.

Uses isspace() to decide what is whitespace and what not.

Definition at line 529 of file str.cpp.

String Common::String::vformat ( const char *  fmt,
va_list  args 
) [static]

Print formatted data into a String object.

Similar to vsprintf, except that it stores the result in (variably sized) String instead of a fixed size buffer.

Definition at line 683 of file str.cpp.

void Common::String::wordWrap ( const uint32  maxLength  ) 

Wraps the text in the string to the given line maximum.

Lines will be broken at any whitespace character. New lines are assumed to be represented using '
'.

This is a very basic line wrap which does not perform tab stop calculation, consecutive whitespace collapsing, auto-hyphenation, or line balancing.

Definition at line 551 of file str.cpp.


Member Data Documentation

union { ... } [protected]
const uint32 Common::String::_builtinCapacity = 32 - sizeof(uint32) - sizeof(char *) [static, protected]

The size of the internal storage.

Increasing this means less heap allocations are needed, at the cost of more stack memory usage, and of course lots of wasted memory. Empirically, 90% or more of all String instances are less than 32 chars long. If a platform is very short on stack space, it would be possible to lower this. A value of 24 still seems acceptable, though considerably worse, while 16 seems to be the lowest you want to go... Anything lower than 8 makes no sense, since that's the size of member _extern (on 32 bit machines; 12 bytes on systems with 64bit pointers).

Definition at line 78 of file str.h.

Definition at line 105 of file str.h.

struct { ... } Common::String::_extern

External string storage data -- the refcounter, and the capacity of the string _str points to.

int* Common::String::_refCount [mutable]

Definition at line 104 of file str.h.

Length of the string.

Stored to avoid having to call strlen a lot. Yes, we limit ourselves to strings shorter than 4GB -- on purpose :-).

Definition at line 85 of file str.h.

Internal string storage.

Definition at line 98 of file str.h.

char* Common::String::_str [protected]

Pointer to the actual string storage.

Either points to _storage, or to a block allocated on the heap via malloc.

Definition at line 91 of file str.h.

const uint32 Common::String::npos = 0xFFFFFFFF [static]

Definition at line 52 of file str.h.


The documentation for this class was generated from the following files:


Generated on Sat Sep 12 2020 05:04:28 for ResidualVM by doxygen 1.7.1
curved edge   curved edge