SString Class Reference
[Utility Classes and Functions]

#include <support/String.h>

Detailed Description

UTF8 string container.

This class represents a UTF-8 string. It includes a variety of common string operations as methods (in fact as way too many methods); additional less common operations are available in the StringUtils.h header.

SString uses copy-on-write for its internal data buffer, so it is efficient to copy (and usually to convert back and forth with SValue, which shares the same copy-on-write mechanism).

Appending

Adding to the end of the string.

SString & Append (char, int32_t count)

SString & Append (const char *, int32_t length)

SString & Append (const SString &, int32_t length)

SString & Append (const char *)

SString & Append (const SString &)

SString & operator+= (char)

SString & operator+= (const char *)

SString & operator+= (const SString &)

UTF-8 Utility Functions

Conveniences for working with the string UTF-8 data as distinct Unicode characters.

SString & AppendChar (wchar32_t unicode)

Appends the unicode character (unicode scalar value) to the string.

wchar32_t CharAt (int32_t index) const

Returns the unicode value for the character that starts at index.

int32_t CharLength (int32_t index) const

Returns the length of the utf-8 character with its first byte at the given index.

int32_t CountChars () const

Returns number of utf-8 characters in string.

int32_t FirstForChar (int32_t index) const

Returns the index of the first byte of the utf-8 character that includes the byte at the index given.

int32_t NextChar (int32_t index) const

Returns the index of the first byte of the utf-8 character after the one that starts at the index given.

int32_t NextCharFor (int32_t index) const

Returns the index of the first byte of the utf-8 character after the one that includes the byte at the index given.

Fast Low-level Manipulation

Direct access to the string buffer for efficient implementation of more custom string algorithms.

void BeginBuffering ()

Start buffering mode on the string data.

void EndBuffering ()

Stop BeginBuffering() mode.

char * LockBuffer (int32_t maxLength)

Retrieve raw string buffer for editing.

void Pool ()

Make sure string is in the SSharedBuffer pool.

const SSharedBuffer * SharedBuffer () const

Get the SSharedBuffer that the SString is using.

SString & UnlockBuffer (int32_t length=-1)

Finish using SString as C-string, adjusting length.

Access

Retrieving the string and information about it.

char ByteAt (int32_t index) const

Checked (safely bounded) character access.

bool IsNumber (int32_t base=10) const

Checks the string for a valid representation of a number in the base.

int32_t Length () const

Retrieve string length (does not require a strlen()).

void MakeEmpty ()

Remove all data from string.

operator const char * () const

Automagic cast to a C string.

char operator[] (size_t index) const

Unchecked character access.

const char * String () const

Return null-terminated C string.

static const SString & EmptyString ()

Retrieve empty SString constant.

Case Conversions

Lowercase to uppercase, or uppercase to lowercase.

SString & Capitalize ()

Converts first character to upper-case, rest to lower-case.

SString & CapitalizeEachWord ()

Converts first character in each white-space-separated word to upper-case, rest to lower-case.

SString & ToLower (int32_t first, int32_t length)

Convert the supplied range.

SString & ToLower ()

Convert the whole string.

SString & ToUpper (int32_t first, int32_t length)

Convert the supplied range.

SString & ToUpper ()

Convert the whole string.

Escaping and Descaping

Adding and removing escape sequences to protect special characters.

SString & CharacterDeescape (char escapeChar)

SString & CharacterDeescape (const char *original, char escapeChar)

SString & CharacterEscape (const char *setOfCharsToEscape, char escapeWith)

SString & CharacterEscape (const char *original, const char *setOfCharsToEscape, char escapeWith)

Removing

Deleting characters from the string.

SString & Compact (const char *setOfCharsToCompact, char *replacementChar)

SString & Compact (const char *setOfCharsToCompact)

void MoveInto (char *into, int32_t from, int32_t length)

Caller must guarantee that into is large enough.

SString & MoveInto (SString &into, int32_t from, int32_t length)

SString & Remove (int32_t from, int32_t length)

SString & RemoveAll (const char *)

SString & RemoveAll (const SString &)

SString & RemoveFirst (const char *)

SString & RemoveFirst (const SString &)

SString & RemoveLast (const char *)

SString & RemoveLast (const SString &)

SString & RemoveSet (const char *setOfCharsToRemove)

SString & Truncate (int32_t newLength)

strcmp()-Style Comparison

Comparison methods with strcmp()-like results.

int Compare (const char *, int32_t n) const

int Compare (const SString &, int32_t n) const

int Compare (const char *) const

int Compare (const SString &) const

int ICompare (const char *, int32_t n) const

int ICompare (const SString &, int32_t n) const

int ICompare (const char *) const

int ICompare (const SString &) const

Substring Copying

Copying a portion of the string to somewhere else.

void CopyInto (char *into, int32_t fromOffset, int32_t length) const

Caller guarantees that into is large enough.

SString & CopyInto (SString &into, int32_t fromOffset, int32_t length) const

Returns into ref as it's result.

Searching

Finding characters inside the string.

int32_t FindFirst (char, int32_t fromOffset) const

int32_t FindFirst (char) const

int32_t FindFirst (const char *, int32_t fromOffset) const

int32_t FindFirst (const SString &, int32_t fromOffset) const

int32_t FindFirst (const char *) const

int32_t FindFirst (const SString &) const

int32_t FindLast (char, int32_t fromOffset) const

int32_t FindLast (char) const

int32_t FindLast (const char *, int32_t beforeOffset) const

int32_t FindLast (const SString &, int32_t beforeOffset) const

int32_t FindLast (const char *) const

int32_t FindLast (const SString &) const

int32_t FindSetFirst (const char *setOfChars, int32_t fromOffset)

int32_t FindSetFirst (const char *setOfChars)

int32_t FindSetLast (const char *setOfChars, int32_t beforeOffset)

int32_t FindSetLast (const char *setOfChars)

int32_t IFindFirst (const char *, int32_t fromOffset) const

int32_t IFindFirst (const SString &, int32_t fromOffset) const

int32_t IFindFirst (const char *) const

int32_t IFindFirst (const SString &) const

int32_t IFindLast (const char *, int32_t beforeOffset) const

int32_t IFindLast (const SString &, int32_t beforeOffset) const

int32_t IFindLast (const char *) const

int32_t IFindLast (const SString &) const

Inserting

Adding to the middle of the string.

SString & Insert (char, int32_t count, int32_t pos)

SString & Insert (const SString &, int32_t fromOffset, int32_t length, int32_t pos)

SString & Insert (const SString &, int32_t length, int32_t pos)

SString & Insert (const SString &, int32_t pos)

SString & Insert (const char *, int32_t fromOffset, int32_t length, int32_t pos)

SString & Insert (const char *, int32_t length, int32_t pos)

SString & Insert (const char *, int32_t pos)

Replacing

Changing characters inside the string.

SString & IReplace (const char *replaceThis, const char *withThis, int32_t maxReplaceCount, int32_t fromOffset=0)

SString & IReplace (char replaceThis, char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)

SString & IReplaceAll (const char *replaceThis, const char *withThis, int32_t fromOffset=0)

SString & IReplaceAll (char replaceThis, char withThis, int32_t fromOffset=0)

SString & IReplaceFirst (const char *replaceThis, const char *withThis)

SString & IReplaceFirst (char replaceThis, char withThis)

SString & IReplaceLast (const char *replaceThis, const char *withThis)

SString & IReplaceLast (char replaceThis, char withThis)

SString & Replace (const char *replaceThis, const char *withThis, int32_t maxReplaceCount, int32_t fromOffset=0)

SString & Replace (char replaceThis, char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)

SString & ReplaceAll (const char *replaceThis, const char *withThis, int32_t fromOffset=0)

SString & ReplaceAll (char replaceThis, char withThis, int32_t fromOffset=0)

SString & ReplaceFirst (const char *replaceThis, const char *withThis)

SString & ReplaceFirst (char replaceThis, char withThis)

SString & ReplaceLast (const char *replaceThis, const char *withThis)

SString & ReplaceLast (char replaceThis, char withThis)

SString & ReplaceSet (const char *setOfChars, const char *with)

SString & ReplaceSet (const char *setOfChars, char with)

Handling Whitespace

Commmon whitespace-related operations.

bool IsOnlyWhitespace () const

Anything but whitespace in the string?

SString & Mush ()

Get rid of redundant whitespace.

SString & StripWhitespace ()

Removes all whitespace.

SString & Trim ()

Remove all leading and trailing whitespace.

Comparison

Standard C++ comparion operators.

bool operator!= (const char *) const

bool operator!= (const SString &) const

bool operator< (const char *) const

bool operator< (const SString &) const

bool operator<= (const char *) const

bool operator<= (const SString &) const

bool operator== (const char *) const

bool operator== (const SString &) const

bool operator> (const char *) const

bool operator> (const SString &) const

bool operator>= (const char *) const

bool operator>= (const SString &) const

SPrintf Replacements

Slower than sprintf but type and overflow safe.

SString & operator<< (float)

Float output hardcodes %.2f style formatting.

SString & operator<< (int64_t)

Float output hardcodes %.2f style formatting.

SString & operator<< (uint64_t)

Float output hardcodes %.2f style formatting.

SString & operator<< (long)

Float output hardcodes %.2f style formatting.

SString & operator<< (unsigned long)

Float output hardcodes %.2f style formatting.

SString & operator<< (unsigned int)

Float output hardcodes %.2f style formatting.

SString & operator<< (int)

Float output hardcodes %.2f style formatting.

SString & operator<< (char)

Float output hardcodes %.2f style formatting.

SString & operator<< (const SString &)

Float output hardcodes %.2f style formatting.

SString & operator<< (const char *)

Float output hardcodes %.2f style formatting.

Assignment

Replacing the string with something entirely different.

SString & operator= (const char *)

SString & operator= (const SString &)

SString & Printf (const char *fmt,...)

Set string using a printf-style format.

SString & SetTo (char, int32_t count)

SString & SetTo (const SString &, int32_t length)

SString & SetTo (const SString &from)

SString & SetTo (const char *, int32_t length)

SString & SetTo (const char *)

void Swap (SString &with)

Path Handling

Manipulating string as a filename path.

status_t PathAppend (const char *leaf, bool normalize=false)

Append a path to the current path string.

status_t PathAppend (const SString &leaf, bool normalize=false)

Append a path to the current path string.

status_t PathGetParent (SString *parentPath) const

Return the parent portion of the path.

status_t PathGetRoot (SString *root) const

Retrieve the root part of the path and place it in root.

const char * PathLeaf (void) const

Append a path to the current path string.

status_t PathNormalize ()

Return the end of the string representing the leaf node in the path.

status_t PathRemoveRoot (SString *root)

Remove root part of path and place it in root.

status_t PathSetTo (const char *dir, const char *leaf=NULL, bool normalize=false)

Set string to a path.

status_t PathSetTo (const SString &dir, const SString &leaf=B_EMPTY_STRING, bool normalize=false)

Set string to a path.

static const char * PathDelimiter ()

The character that is used to separate path segments.

Prepending

Adding to the front of the string.

SString & Prepend (char, int32_t count)

SString & Prepend (const SString &, int32_t)

SString & Prepend (const char *, int32_t)

SString & Prepend (const SString &)

SString & Prepend (const char *)

Bookkeeping

Creation, destruction.

SString (const SSharedBuffer *buf)

SString (const char *, int32_t maxLength)

SString (const SString &)

SString (int32_t)

SString (const char *)

SString ()

~SString ()

static status_t SelfQC ()

Run internal QC tests. Only available on debug builds.

Protected Attributes

const char * _privateData

Constructor & Destructor Documentation

SString ( )

SString ( const char * ) [explicit]

SString ( int32_t ) [explicit]

SString ( const SString & )

SString ( const char * ,

int32_t maxLength

)

SString ( const SSharedBuffer * buf )

~SString ( )

Member Function Documentation

SString & Append ( char ,

int32_t count

)

SString & Append ( const char * ,

int32_t length

)

SString & Append ( const SString & ,

int32_t length

)

SString & Append ( const char * ) [inline]

SString & Append ( const SString & ) [inline]

SString & AppendChar ( wchar32_t unicode )

Appends the unicode character (unicode scalar value) to the string.

void BeginBuffering ( )

Start buffering mode on the string data.
This provides more efficient growth and reduction of the string size, since it doesn't have to reallocate its memory every time. Be sure to call EndBuffering() before giving the string to anyone else.

char ByteAt ( int32_t index ) const [inline]

Checked (safely bounded) character access.

SString & Capitalize ( )

Converts first character to upper-case, rest to lower-case.

SString & CapitalizeEachWord ( )

Converts first character in each white-space-separated word to upper-case, rest to lower-case.

SString & CharacterDeescape ( char escapeChar )

Remove the escaping characters escapeChar from the string

SString & CharacterDeescape ( const char * original,

char escapeChar

)

Copy original into the string removing the escaping characters escapeChar

SString & CharacterEscape ( const char * setOfCharsToEscape,

char escapeWith

)

Escapes characters specified in setOfCharsToEscape by prepending them with escapeWith

SString & CharacterEscape ( const char * original,

const char * setOfCharsToEscape,

char escapeWith

)

Copies original into this, escaping characters specified in setOfCharsToEscape by prepending them with escapeWith

wchar32_t CharAt ( int32_t index ) const

Returns the unicode value for the character that starts at index.
Returns the invalid unicode character 0xffff if there isn't a whole character starting at index (note this is 0xffff not 0xffffffff, it is not sign-extended).

int32_t CharLength ( int32_t index ) const

Returns the length of the utf-8 character with its first byte at the given index.
If index is greater than the length or less than 0, this function returns -1. If index is not the first byte of a character, this function returns 0.

SString & Compact ( const char * setOfCharsToCompact,

char * replacementChar

)

SString & Compact ( const char * setOfCharsToCompact )

int Compare ( const char * ,

int32_t n

) const

int Compare ( const SString & ,

int32_t n

) const

int Compare ( const char * ) const

int Compare ( const SString & ) const

void CopyInto ( char * into,

int32_t fromOffset,

int32_t length

) const

Caller guarantees that into is large enough.

SString & CopyInto ( SString & into,

int32_t fromOffset,

int32_t length

) const

Returns into ref as it's result.
Doesn't do anything if into is this.

int32_t CountChars ( ) const

Returns number of utf-8 characters in string.
Keep in mind that the number of characters in the string is not necessarily the number of glyphs that will appear if you draw this string.

const SString & EmptyString ( ) [static]

Retrieve empty SString constant.
Normally you would want to use the default SString constructor, but this is handy for things like default parameters, or when a const SString& is desired, and you don't have one to provide.

void EndBuffering ( )

Stop BeginBuffering() mode.

int32_t FindFirst ( char ,

int32_t fromOffset

) const

int32_t FindFirst ( char ) const

int32_t FindFirst ( const char * ,

int32_t fromOffset

) const

int32_t FindFirst ( const SString & ,

int32_t fromOffset

) const

int32_t FindFirst ( const char * ) const

int32_t FindFirst ( const SString & ) const

int32_t FindLast ( char ,

int32_t fromOffset

) const

int32_t FindLast ( char ) const

int32_t FindLast ( const char * ,

int32_t beforeOffset

) const

int32_t FindLast ( const SString & ,

int32_t beforeOffset

) const

int32_t FindLast ( const char * ) const

int32_t FindLast ( const SString & ) const

int32_t FindSetFirst ( const char * setOfChars,

int32_t fromOffset

)

int32_t FindSetFirst ( const char * setOfChars )

int32_t FindSetLast ( const char * setOfChars,

int32_t beforeOffset

)

int32_t FindSetLast ( const char * setOfChars )

int32_t FirstForChar ( int32_t index ) const

Returns the index of the first byte of the utf-8 character that includes the byte at the index given.
Returns a negative value if it can not be determined (which means the string isn't valid utf-8), or the index is greater than the length of the string, or if the index is the index of the NULL terminator.

int ICompare ( const char * ,

int32_t n

) const

int ICompare ( const SString & ,

int32_t n

) const

int ICompare ( const char * ) const

int ICompare ( const SString & ) const

int32_t IFindFirst ( const char * ,

int32_t fromOffset

) const

int32_t IFindFirst ( const SString & ,

int32_t fromOffset

) const

int32_t IFindFirst ( const char * ) const

int32_t IFindFirst ( const SString & ) const

int32_t IFindLast ( const char * ,

int32_t beforeOffset

) const

int32_t IFindLast ( const SString & ,

int32_t beforeOffset

) const

int32_t IFindLast ( const char * ) const

int32_t IFindLast ( const SString & ) const

SString & Insert ( char ,

int32_t count,

int32_t pos

)

SString & Insert ( const SString & ,

int32_t fromOffset,

int32_t length,

int32_t pos

)

SString & Insert ( const SString & ,

int32_t length,

int32_t pos

)

SString & Insert ( const SString & ,

int32_t pos

)

SString & Insert ( const char * ,

int32_t fromOffset,

int32_t length,

int32_t pos

)

SString & Insert ( const char * ,

int32_t length,

int32_t pos

)

SString & Insert ( const char * ,

int32_t pos

)

SString & IReplace ( const char * replaceThis,

const char * withThis,

int32_t maxReplaceCount,

int32_t fromOffset = 0

)

SString & IReplace ( char replaceThis,

char withThis,

int32_t maxReplaceCount,

int32_t fromOffset = 0

)

SString & IReplaceAll ( const char * replaceThis,

const char * withThis,

int32_t fromOffset = 0

)

SString & IReplaceAll ( char replaceThis,

char withThis,

int32_t fromOffset = 0

)

SString & IReplaceFirst ( const char * replaceThis,

const char * withThis

)

SString & IReplaceFirst ( char replaceThis,

char withThis

)

SString & IReplaceLast ( const char * replaceThis,

const char * withThis

)

SString & IReplaceLast ( char replaceThis,

char withThis

)

bool IsNumber ( int32_t base = 10 ) const

Checks the string for a valid representation of a number in the base.

bool IsOnlyWhitespace ( ) const

Anything but whitespace in the string?
Returns true if the string contains one or more non-whitespace characters, or the length is zero. Returns false otherwise.

int32_t Length ( ) const [inline]

Retrieve string length (does not require a strlen()).

char * LockBuffer ( int32_t maxLength )

Retrieve raw string buffer for editing.
Make room for characters to be added by C-string like manipulation. Returns the equivalent of String() as an editable buffer. maxLength does not need to include space for the trailing zero -- the space allocated will be maxLength+1 to make room for it. It is illegal to call other SString routines that rely on data/length consistency until UnlockBuffer() sets things up again.

void MakeEmpty ( )

Remove all data from string.

void MoveInto ( char * into,

int32_t from,

int32_t length

)

Caller must guarantee that into is large enough.

SString & MoveInto ( SString & into,

int32_t from,

int32_t length

)

SString & Mush ( )

Get rid of redundant whitespace.
Removes all leading and trailing whitespace, and converts all other whitepace to exactly one space character

int32_t NextChar ( int32_t index ) const

Returns the index of the first byte of the utf-8 character after the one that starts at the index given.
This is faster than NextCharAfter, but index must be the index of the first byte of the character.

int32_t NextCharFor ( int32_t index ) const

Returns the index of the first byte of the utf-8 character after the one that includes the byte at the index given.
The returned index will count up to Length() (when called on the last character in the string) and then become negative.

operator const char * ( ) const [inline]

Automagic cast to a C string.

Todo:
This should be removed!

bool operator!= ( const char * ) const [inline]

bool operator!= ( const SString & ) const [inline]

SString & operator+= ( char )

SString & operator+= ( const char * )

SString & operator+= ( const SString & ) [inline]

bool operator< ( const char * ) const

bool operator< ( const SString & ) const [inline]

SString & operator<< ( float )

Float output hardcodes %.2f style formatting.

SString & operator<< ( int64_t )

Float output hardcodes %.2f style formatting.

SString & operator<< ( uint64_t )

Float output hardcodes %.2f style formatting.

SString & operator<< ( long )

Float output hardcodes %.2f style formatting.

SString & operator<< ( unsigned long )

Float output hardcodes %.2f style formatting.

SString & operator<< ( unsigned int )

Float output hardcodes %.2f style formatting.

SString & operator<< ( int )

Float output hardcodes %.2f style formatting.

SString & operator<< ( char )

Float output hardcodes %.2f style formatting.

SString & operator<< ( const SString & )

Float output hardcodes %.2f style formatting.

SString & operator<< ( const char * )

Float output hardcodes %.2f style formatting.

bool operator<= ( const char * ) const

bool operator<= ( const SString & ) const [inline]

SString & operator= ( const char * )

SString & operator= ( const SString & )

bool operator== ( const char * ) const

bool operator== ( const SString & ) const [inline]

bool operator> ( const char * ) const

bool operator> ( const SString & ) const [inline]

bool operator>= ( const char * ) const

bool operator>= ( const SString & ) const [inline]

char operator[] ( size_t index ) const [inline]

Unchecked character access.

status_t PathAppend ( const char * leaf,

bool normalize = false

)

Append a path to the current path string.
If leaf is an absolute path, it will replace the current path. normalize is as per PathSetTo().

status_t PathAppend ( const SString & leaf,

bool normalize = false

)

Append a path to the current path string.
If leaf is an absolute path, it will replace the current path. normalize is as per PathSetTo().

const char * PathDelimiter ( ) [static]

The character that is used to separate path segments.

status_t PathGetParent ( SString * parentPath ) const

Return the parent portion of the path.
This is all of the path up to but not including PathLeaf().

status_t PathGetRoot ( SString * root ) const

Retrieve the root part of the path and place it in root.

const char * PathLeaf ( void ) const

Append a path to the current path string.
If leaf is an absolute path, it will replace the current path. normalize is as per PathSetTo().

status_t PathNormalize ( )

Return the end of the string representing the leaf node in the path.

status_t PathRemoveRoot ( SString * root )

Remove root part of path and place it in root.
This is often used for walking a path -- root contains the name of the entry at the current level, and this is the remaining part of the path that must be processed.

status_t PathSetTo ( const char * dir,

const char * leaf = NULL,

bool normalize = false

)

Set string to a path.
The dir and leaf are concatenated to form a full valid path. If normalize is true, the path segments such as ".." and "." will be removed.

status_t PathSetTo ( const SString & dir,

const SString & leaf = B_EMPTY_STRING,

bool normalize = false

)

Set string to a path.
The dir and leaf are concatenated to form a full valid path. If normalize is true, the path segments such as ".." and "." will be removed.

void Pool ( )

Make sure string is in the SSharedBuffer pool.

SString & Prepend ( char ,

int32_t count

)

SString & Prepend ( const SString & ,

int32_t

)

SString & Prepend ( const char * ,

int32_t

)

SString & Prepend ( const SString & )

SString & Prepend ( const char * )

SString & Printf ( const char * fmt,

...

)

Set string using a printf-style format.

SString & Remove ( int32_t from,

int32_t length

)

SString & RemoveAll ( const char * )

SString & RemoveAll ( const SString & )

SString & RemoveFirst ( const char * )

SString & RemoveFirst ( const SString & )

SString & RemoveLast ( const char * )

SString & RemoveLast ( const SString & )

SString & RemoveSet ( const char * setOfCharsToRemove )

SString & Replace ( const char * replaceThis,

const char * withThis,

int32_t maxReplaceCount,

int32_t fromOffset = 0

)

SString & Replace ( char replaceThis,

char withThis,

int32_t maxReplaceCount,

int32_t fromOffset = 0

)

SString & ReplaceAll ( const char * replaceThis,

const char * withThis,

int32_t fromOffset = 0

)

SString & ReplaceAll ( char replaceThis,

char withThis,

int32_t fromOffset = 0

)

SString & ReplaceFirst ( const char * replaceThis,

const char * withThis

)

SString & ReplaceFirst ( char replaceThis,

char withThis

)

SString & ReplaceLast ( const char * replaceThis,

const char * withThis

)

SString & ReplaceLast ( char replaceThis,

char withThis

)

SString & ReplaceSet ( const char * setOfChars,

const char * with

)

SString & ReplaceSet ( const char * setOfChars,

char with

)

status_t SelfQC ( ) [static]

Run internal QC tests. Only available on debug builds.

SString & SetTo ( char ,

int32_t count

)

SString & SetTo ( const SString & ,

int32_t length

)

SString & SetTo ( const SString & from )

SString & SetTo ( const char * ,

int32_t length

)

SString & SetTo ( const char * ) [inline]

const SSharedBuffer * SharedBuffer ( ) const

Get the SSharedBuffer that the SString is using.
Returns NULL if the string is empty.

const char * String ( ) const [inline]

Return null-terminated C string.

SString & StripWhitespace ( )

Removes all whitespace.

void Swap ( SString & with )

SString & ToLower ( int32_t first,

int32_t length

)

Convert the supplied range.

SString & ToLower ( )

Convert the whole string.

SString & ToUpper ( int32_t first,

int32_t length

)

Convert the supplied range.

SString & ToUpper ( )

Convert the whole string.

SString & Trim ( )

Remove all leading and trailing whitespace.

SString & Truncate ( int32_t newLength )

SString & UnlockBuffer ( int32_t length = -1 )

Finish using SString as C-string, adjusting length.
If no length passed in, strlen of internal data is used to determine it. SString is in consistent state after this. If you supply a new length, it should not include the trailing zero -- this function will make room for it, and ensure it is zero.

Member Data Documentation

const char* _privateData [protected]

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


Appending
Adding to the end of the string.
SString &	Append (char, int32_t count)
SString &	Append (const char *, int32_t length)
SString &	Append (const SString &, int32_t length)
SString &	Append (const char *)
SString &	Append (const SString &)
SString &	operator+= (char)
SString &	operator+= (const char *)
SString &	operator+= (const SString &)
UTF-8 Utility Functions
Conveniences for working with the string UTF-8 data as distinct Unicode characters.
SString &	AppendChar (wchar32_t unicode)
	Appends the unicode character (unicode scalar value) to the string.
wchar32_t	CharAt (int32_t index) const
	Returns the unicode value for the character that starts at index.
int32_t	CharLength (int32_t index) const
	Returns the length of the utf-8 character with its first byte at the given index.
int32_t	CountChars () const
	Returns number of utf-8 characters in string.
int32_t	FirstForChar (int32_t index) const
	Returns the index of the first byte of the utf-8 character that includes the byte at the index given.
int32_t	NextChar (int32_t index) const
	Returns the index of the first byte of the utf-8 character after the one that starts at the index given.
int32_t	NextCharFor (int32_t index) const
	Returns the index of the first byte of the utf-8 character after the one that includes the byte at the index given.
Fast Low-level Manipulation
Direct access to the string buffer for efficient implementation of more custom string algorithms.
void	BeginBuffering ()
	Start buffering mode on the string data.
void	EndBuffering ()
	Stop BeginBuffering() mode.
char *	LockBuffer (int32_t maxLength)
	Retrieve raw string buffer for editing.
void	Pool ()
	Make sure string is in the SSharedBuffer pool.
const SSharedBuffer *	SharedBuffer () const
	Get the SSharedBuffer that the SString is using.
SString &	UnlockBuffer (int32_t length=-1)
	Finish using SString as C-string, adjusting length.
Access
Retrieving the string and information about it.
char	ByteAt (int32_t index) const
	Checked (safely bounded) character access.
bool	IsNumber (int32_t base=10) const
	Checks the string for a valid representation of a number in the base.
int32_t	Length () const
	Retrieve string length (does not require a strlen()).
void	MakeEmpty ()
	Remove all data from string.
	operator const char * () const
	Automagic cast to a C string.
char	operator[] (size_t index) const
	Unchecked character access.
const char *	String () const
	Return null-terminated C string.
static const SString &	EmptyString ()
	Retrieve empty SString constant.
Case Conversions
Lowercase to uppercase, or uppercase to lowercase.
SString &	Capitalize ()
	Converts first character to upper-case, rest to lower-case.
SString &	CapitalizeEachWord ()
	Converts first character in each white-space-separated word to upper-case, rest to lower-case.
SString &	ToLower (int32_t first, int32_t length)
	Convert the supplied range.
SString &	ToLower ()
	Convert the whole string.
SString &	ToUpper (int32_t first, int32_t length)
	Convert the supplied range.
SString &	ToUpper ()
	Convert the whole string.
Escaping and Descaping
Adding and removing escape sequences to protect special characters.
SString &	CharacterDeescape (char escapeChar)
SString &	CharacterDeescape (const char *original, char escapeChar)
SString &	CharacterEscape (const char *setOfCharsToEscape, char escapeWith)
SString &	CharacterEscape (const char original, const char setOfCharsToEscape, char escapeWith)
Removing
Deleting characters from the string.
SString &	Compact (const char setOfCharsToCompact, char replacementChar)
SString &	Compact (const char *setOfCharsToCompact)
void	MoveInto (char *into, int32_t from, int32_t length)
	Caller must guarantee that into is large enough.
SString &	MoveInto (SString &into, int32_t from, int32_t length)
SString &	Remove (int32_t from, int32_t length)
SString &	RemoveAll (const char *)
SString &	RemoveAll (const SString &)
SString &	RemoveFirst (const char *)
SString &	RemoveFirst (const SString &)
SString &	RemoveLast (const char *)
SString &	RemoveLast (const SString &)
SString &	RemoveSet (const char *setOfCharsToRemove)
SString &	Truncate (int32_t newLength)
strcmp()-Style Comparison
Comparison methods with strcmp()-like results.
int	Compare (const char *, int32_t n) const
int	Compare (const SString &, int32_t n) const
int	Compare (const char *) const
int	Compare (const SString &) const
int	ICompare (const char *, int32_t n) const
int	ICompare (const SString &, int32_t n) const
int	ICompare (const char *) const
int	ICompare (const SString &) const
Substring Copying
Copying a portion of the string to somewhere else.
void	CopyInto (char *into, int32_t fromOffset, int32_t length) const
	Caller guarantees that into is large enough.
SString &	CopyInto (SString &into, int32_t fromOffset, int32_t length) const
	Returns into ref as it's result.
Searching
Finding characters inside the string.
int32_t	FindFirst (char, int32_t fromOffset) const
int32_t	FindFirst (char) const
int32_t	FindFirst (const char *, int32_t fromOffset) const
int32_t	FindFirst (const SString &, int32_t fromOffset) const
int32_t	FindFirst (const char *) const
int32_t	FindFirst (const SString &) const
int32_t	FindLast (char, int32_t fromOffset) const
int32_t	FindLast (char) const
int32_t	FindLast (const char *, int32_t beforeOffset) const
int32_t	FindLast (const SString &, int32_t beforeOffset) const
int32_t	FindLast (const char *) const
int32_t	FindLast (const SString &) const
int32_t	FindSetFirst (const char *setOfChars, int32_t fromOffset)
int32_t	FindSetFirst (const char *setOfChars)
int32_t	FindSetLast (const char *setOfChars, int32_t beforeOffset)
int32_t	FindSetLast (const char *setOfChars)
int32_t	IFindFirst (const char *, int32_t fromOffset) const
int32_t	IFindFirst (const SString &, int32_t fromOffset) const
int32_t	IFindFirst (const char *) const
int32_t	IFindFirst (const SString &) const
int32_t	IFindLast (const char *, int32_t beforeOffset) const
int32_t	IFindLast (const SString &, int32_t beforeOffset) const
int32_t	IFindLast (const char *) const
int32_t	IFindLast (const SString &) const
Inserting
Adding to the middle of the string.
SString &	Insert (char, int32_t count, int32_t pos)
SString &	Insert (const SString &, int32_t fromOffset, int32_t length, int32_t pos)
SString &	Insert (const SString &, int32_t length, int32_t pos)
SString &	Insert (const SString &, int32_t pos)
SString &	Insert (const char *, int32_t fromOffset, int32_t length, int32_t pos)
SString &	Insert (const char *, int32_t length, int32_t pos)
SString &	Insert (const char *, int32_t pos)
Replacing
Changing characters inside the string.
SString &	IReplace (const char replaceThis, const char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)
SString &	IReplace (char replaceThis, char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)
SString &	IReplaceAll (const char replaceThis, const char withThis, int32_t fromOffset=0)
SString &	IReplaceAll (char replaceThis, char withThis, int32_t fromOffset=0)
SString &	IReplaceFirst (const char replaceThis, const char withThis)
SString &	IReplaceFirst (char replaceThis, char withThis)
SString &	IReplaceLast (const char replaceThis, const char withThis)
SString &	IReplaceLast (char replaceThis, char withThis)
SString &	Replace (const char replaceThis, const char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)
SString &	Replace (char replaceThis, char withThis, int32_t maxReplaceCount, int32_t fromOffset=0)
SString &	ReplaceAll (const char replaceThis, const char withThis, int32_t fromOffset=0)
SString &	ReplaceAll (char replaceThis, char withThis, int32_t fromOffset=0)
SString &	ReplaceFirst (const char replaceThis, const char withThis)
SString &	ReplaceFirst (char replaceThis, char withThis)
SString &	ReplaceLast (const char replaceThis, const char withThis)
SString &	ReplaceLast (char replaceThis, char withThis)
SString &	ReplaceSet (const char setOfChars, const char with)
SString &	ReplaceSet (const char *setOfChars, char with)
Handling Whitespace
Commmon whitespace-related operations.
bool	IsOnlyWhitespace () const
	Anything but whitespace in the string?
SString &	Mush ()
	Get rid of redundant whitespace.
SString &	StripWhitespace ()
	Removes all whitespace.
SString &	Trim ()
	Remove all leading and trailing whitespace.
Comparison
Standard C++ comparion operators.
bool	operator!= (const char *) const
bool	operator!= (const SString &) const
bool	operator< (const char *) const
bool	operator< (const SString &) const
bool	operator<= (const char *) const
bool	operator<= (const SString &) const
bool	operator== (const char *) const
bool	operator== (const SString &) const
bool	operator> (const char *) const
bool	operator> (const SString &) const
bool	operator>= (const char *) const
bool	operator>= (const SString &) const
SPrintf Replacements
Slower than sprintf but type and overflow safe.
SString &	operator<< (float)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (int64_t)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (uint64_t)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (long)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (unsigned long)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (unsigned int)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (int)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (char)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (const SString &)
	Float output hardcodes %.2f style formatting.
SString &	operator<< (const char *)
	Float output hardcodes %.2f style formatting.
Assignment
Replacing the string with something entirely different.
SString &	operator= (const char *)
SString &	operator= (const SString &)
SString &	Printf (const char *fmt,...)
	Set string using a printf-style format.
SString &	SetTo (char, int32_t count)
SString &	SetTo (const SString &, int32_t length)
SString &	SetTo (const SString &from)
SString &	SetTo (const char *, int32_t length)
SString &	SetTo (const char *)
void	Swap (SString &with)
Path Handling
Manipulating string as a filename path.
status_t	PathAppend (const char *leaf, bool normalize=false)
	Append a path to the current path string.
status_t	PathAppend (const SString &leaf, bool normalize=false)
	Append a path to the current path string.
status_t	PathGetParent (SString *parentPath) const
	Return the parent portion of the path.
status_t	PathGetRoot (SString *root) const
	Retrieve the root part of the path and place it in root.
const char *	PathLeaf (void) const
	Append a path to the current path string.
status_t	PathNormalize ()
	Return the end of the string representing the leaf node in the path.
status_t	PathRemoveRoot (SString *root)
	Remove root part of path and place it in root.
status_t	PathSetTo (const char dir, const char leaf=NULL, bool normalize=false)
	Set string to a path.
status_t	PathSetTo (const SString &dir, const SString &leaf=B_EMPTY_STRING, bool normalize=false)
	Set string to a path.
static const char *	PathDelimiter ()
	The character that is used to separate path segments.
Prepending
Adding to the front of the string.
SString &	Prepend (char, int32_t count)
SString &	Prepend (const SString &, int32_t)
SString &	Prepend (const char *, int32_t)
SString &	Prepend (const SString &)
SString &	Prepend (const char *)
Bookkeeping
Creation, destruction.
	SString (const SSharedBuffer *buf)
	SString (const char *, int32_t maxLength)
	SString (const SString &)
	SString (int32_t)
	SString (const char *)
	SString ()
	~SString ()
static status_t	SelfQC ()
	Run internal QC tests. Only available on debug builds.
Protected Attributes
const char *	_privateData

SString Class Reference [Utility Classes and Functions]

Detailed Description

Appending

UTF-8 Utility Functions

Fast Low-level Manipulation

Access

Case Conversions

Escaping and Descaping

Removing

strcmp()-Style Comparison

Substring Copying

Searching

Inserting

Replacing

Handling Whitespace

Comparison

SPrintf Replacements

Assignment

Path Handling

Prepending

Bookkeeping

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

SString Class Reference
[Utility Classes and Functions]