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 ()
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
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
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.
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
iterator begin ()
iterator end ()
const_iterator begin () const
const_iterator end () const

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)

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 46 of file str.h.


Member Typedef Documentation

typedef const char* Common::String::const_iterator

Definition at line 60 of file str.h.

typedef char* Common::String::iterator

Definition at line 59 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 58 of file str.h.

Definition at line 52 of file str.h.


Constructor & Destructor Documentation

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

Construct a new empty string.

Definition at line 111 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 (  ) 

Definition at line 128 of file str.cpp.


Member Function Documentation

uint64 Common::String::asUint64 (  )  const

Return uint64 corrensponding to String's contents.

Definition at line 405 of file str.cpp.

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

Definition at line 306 of file str.h.

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

Definition at line 320 of file str.h.

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

Definition at line 203 of file str.h.

void Common::String::clear (  ) 

Clears the string, making it empty.

Definition at line 455 of file str.cpp.

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

Definition at line 739 of file str.cpp.

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

Definition at line 743 of file str.cpp.

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

Definition at line 748 of file str.cpp.

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

Definition at line 752 of file str.cpp.

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

Definition at line 396 of file str.cpp.

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

Definition at line 401 of file str.cpp.

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

Definition at line 392 of file str.cpp.

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

Definition at line 216 of file str.cpp.

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

Remove the character at position p from the string.

Definition at line 427 of file str.cpp.

void Common::String::deleteLastChar (  ) 

Remove the last character from the string.

Definition at line 422 of file str.cpp.

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

Definition at line 206 of file str.h.

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

Definition at line 316 of file str.h.

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

Definition at line 324 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 142 of file str.cpp.

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

Definition at line 725 of file str.cpp.

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

Definition at line 721 of file str.cpp.

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

Definition at line 730 of file str.cpp.

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

Definition at line 734 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 436 of file str.cpp.

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

Definition at line 207 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 609 of file str.cpp.

uint Common::String::hash (  )  const

Definition at line 552 of file str.cpp.

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

Definition at line 318 of file str.cpp.

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

Definition at line 322 of file str.cpp.

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

Definition at line 335 of file str.cpp.

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

Definition at line 339 of file str.cpp.

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

Definition at line 352 of file str.cpp.

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

Definition at line 356 of file str.cpp.

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

Definition at line 372 of file str.cpp.

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

Definition at line 376 of file str.cpp.

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

Definition at line 199 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 470 of file str.cpp.

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

Definition at line 105 of file str.h.

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

Definition at line 208 of file str.h.

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

Definition at line 132 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 414 of file str.cpp.

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

Definition at line 418 of file str.cpp.

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

Definition at line 684 of file str.cpp.

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

Definition at line 688 of file str.cpp.

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

Definition at line 281 of file str.cpp.

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

Definition at line 309 of file str.cpp.

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

Definition at line 295 of file str.cpp.

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

Definition at line 693 of file str.cpp.

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

Definition at line 697 of file str.cpp.

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

Definition at line 248 of file str.cpp.

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

Definition at line 270 of file str.cpp.

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

Definition at line 240 of file str.cpp.

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

Definition at line 679 of file str.cpp.

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

Definition at line 675 of file str.cpp.

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

Definition at line 701 of file str.cpp.

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

Definition at line 705 of file str.cpp.

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

Definition at line 210 of file str.h.

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

Definition at line 52 of file str.cpp.

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

Definition at line 568 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 556 of file str.cpp.

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

Definition at line 560 of file str.cpp.

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

Definition at line 564 of file str.cpp.

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

Definition at line 572 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 577 of file str.cpp.

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

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

Definition at line 463 of file str.cpp.

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

Definition at line 204 of file str.h.

void Common::String::toLowercase (  ) 

Convert all characters in the string to lowercase.

Definition at line 480 of file str.cpp.

void Common::String::toUppercase (  ) 

Convert all characters in the string to uppercase.

Definition at line 486 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 492 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 621 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 514 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 74 of file str.h.

Definition at line 101 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 100 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 81 of file str.h.

Internal string storage.

Definition at line 94 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 87 of file str.h.

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

Definition at line 48 of file str.h.


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


Generated on Sat Jul 13 2019 05:03:52 for ResidualVM by doxygen 1.7.1
curved edge   curved edge