cee::Str Class Reference

A general unicode based string class. More...

Public Member Functions

 Str ()
 Constructs a string. More...
 
 Str (const Str &other)
 Constructs a string as a copy of other. More...
 
 Str (const char *theString)
 Creates a string from the given zero terminated char* string. More...
 
 Str (const wchar_t *theString)
 Creates a string from the given zero terminated wchar_t* string. More...
 
 Str (const std::string &theString)
 Creates a string from the given std::string. More...
 
 Str (const std::wstring &theString)
 Creates a string from the given std::wstring. More...
 
 Str (char c)
 Creates a string from the given char. More...
 
Stroperator= (const Str &other)
 Assigns other to this string and returns a reference to this string. More...
 
bool operator== (const Str &rhs) const
 Returns true if this string is equal to the passed string. More...
 
bool operator!= (const Str &rhs) const
 Returns true if this string is not equal to the passed string. More...
 
bool operator< (const Str &rhs) const
 Returns true if this string is less than the passed string. More...
 
const Str operator+ (const Str &rhs) const
 Returns the concatenation of this string and the passed rhs string. More...
 
Stroperator+= (const Str &rhs)
 Sets this string to the concatenation of this string and the passed rhs string. More...
 
Str toLower () const
 Returns a lowercase copy of the string. More...
 
Str toUpper () const
 Returns an uppercase copy of the string. More...
 
Str trimmedRight () const
 Returns string with trailing whitespace removed. More...
 
Str trimmedLeft () const
 Returns string with leading whitespace removed. More...
 
Str trimmed () const
 Returns string with leading and trailing whitespace removed. More...
 
Str simplified () const
 Returns simplified string. More...
 
std::vector< Strsplit (const Str &delimiters=" ") const
 Splits the string into substrings wherever delimiters occurs, and returns the list of those strings. More...
 
size_t find (const Str &str, size_t start=0) const
 Returns the position of the first occurrence of str starting from start. More...
 
bool startsWith (const Str &str) const
 Returns true if the string starts with the given str. More...
 
Str subStr (size_t start, size_t length=npos) const
 Returns the substring of the string starting with index start and the optional given length. More...
 
void replace (const Str &before, const Str &after)
 Replaces occurrences of the string before with the string after. More...
 
const wchar_t * c_str () const
 Returns a null-terminated sequence of wchar_t characters. More...
 
std::string toStdString () const
 Converts a string to an ascii std::string. Non-ascii characters are replaced by a question mark (?) More...
 
std::wstring toStdWString () const
 Converts a string to a std::wstring (std unicode string) More...
 
std::string toUtf8 () const
 Converts a string to a Utf8 encoded string. Non-ascii characters are replaced by their multi-byte UTF8 encoding. More...
 
bool isEmpty () const
 Returns true if the string has no characters, otherwise returns false. More...
 
size_t size () const
 Returns the length of the string. More...
 
double toDouble (bool *ok=NULL) const
 Converts the contents of the string to a double value (if possible) More...
 
double toDouble (double defaultValue) const
 Converts the contents of the string to a double value (if possible) More...
 
float toFloat (bool *ok=NULL) const
 Converts the contents of the string to a float value (if possible) More...
 
float toFloat (float defaultValue) const
 Converts the contents of the string to a float value (if possible) More...
 
int toInt (bool *ok=NULL) const
 Converts the contents of the string to a integer value (if possible) More...
 
int toInt (int defaultValue) const
 Converts the contents of the string to a integer value (if possible) More...
 
unsigned int toUInt (bool *ok=NULL) const
 Converts the contents of the string to an unsigned integer value. More...
 
unsigned int toUInt (unsigned int defaultValue) const
 Converts the contents of the string to an unsigned integer value. More...
 
Str arg (const Str &a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by string a. More...
 
Str arg (char a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the char a. More...
 
Str arg (int a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the integer a. More...
 
Str arg (int64_t a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the 64 bit integer a. More...
 
Str arg (unsigned int a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the unsigned integer a. More...
 
Str arg (uint64_t a, int fieldWidth=0, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the 64 bit unsigned integer a. More...
 
Str arg (float a, int fieldWidth=0, char format= 'g', int precision=-1, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the float a. More...
 
Str arg (double a, int fieldWidth=0, char format= 'g', int precision=-1, char fillChar= ' ') const
 Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the double a. More...
 
void swap (Str &other)
 Exchanges the contents of the two strings. More...
 
bool matches (const Str &wildcard) const
 Returns true if this string matches the given wildcard. More...
 
const void * unspecifiedWCharPointer () const
 Returns unspecified const pointer to the underlying raw wchar_t data array. More...
 

Static Public Member Functions

static Str number (int n)
 Creates a string from the given integer. More...
 
static Str number (unsigned int n)
 Creates a string from the given unsigned integer. More...
 
static Str number (float n, char format= 'g', int precision=-1)
 Converts the given number to a string with the specified format. More...
 
static Str number (double n, char format= 'g', int precision=-1)
 Converts the given number to a string with the specified format. More...
 
static Str numberFromAddress (const void *ptr)
 Returns a string that is a textual representation of the pointer address. More...
 
static Str fromUnspecifiedWCharPointer (const void *voidPtr)
 Constructs a new Str object from an unspecified const pointer to raw wchar_t data. More...
 

Static Public Attributes

static const size_t npos = static_cast<size_t>(-1)
 Same as std::string::npos. This value, when used as the value for a count parameter n in string's member functions, roughly indicates "as many as possible". As a return value it is usually used to indicate failure. More...
 

Detailed Description

A general unicode based string class.

The class supports interop between std::string and std::wstring, as well as const char*. In addition the class has many convenience methods for string manipulation.

Constructor & Destructor Documentation

cee::Str::Str ( )

Constructs a string.

cee::Str::Str ( const Str other)

Constructs a string as a copy of other.

cee::Str::Str ( const char *  theString)

Creates a string from the given zero terminated char* string.

cee::Str::Str ( const wchar_t *  theString)
explicit

Creates a string from the given zero terminated wchar_t* string.

cee::Str::Str ( const std::string &  theString)
explicit

Creates a string from the given std::string.

cee::Str::Str ( const std::wstring &  theString)
explicit

Creates a string from the given std::wstring.

cee::Str::Str ( char  c)
explicit

Creates a string from the given char.

Member Function Documentation

cee::Str cee::Str::arg ( const Str a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by string a.

Parameters
aThe string to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the passed string is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

Str test = Str("Reading file %1 (%2 of %3)").arg(filename).arg(fileIndex + 1).arg(fileCount);
cee::Str cee::Str::arg ( char  a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the char a.

Parameters
aThe character to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

String test = String("Reading file %1 (%2 of %3)").arg(filename).arg(fileIndex + 1).arg(fileCount);
cee::Str cee::Str::arg ( int  a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the integer a.

Parameters
aThe int value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

String test = String("Reading file %1 (%2 of %3)").arg(filename).arg(fileIndex + 1).arg(fileCount);
cee::Str cee::Str::arg ( int64_t  a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the 64 bit integer a.

Parameters
aThe value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.
cee::Str cee::Str::arg ( unsigned int  a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the unsigned integer a.

Parameters
aThe unsigned int value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

String test = String("Reading file %1 (%2 of %3)").arg(filename).arg(fileIndex + 1).arg(fileCount);
cee::Str cee::Str::arg ( uint64_t  a,
int  fieldWidth = 0,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the 64 bit unsigned integer a.

Parameters
aThe value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.
cee::Str cee::Str::arg ( float  a,
int  fieldWidth = 0,
char  format = 'g',
int  precision = -1,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the float a.

Parameters
aThe float value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
format'g': default, 'e' : scientific notation (1.234e4). 'f' : Fixed notation (1234.0)
precisionThe precision for floating-point values. Only used for 'f' and 'e'
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

Str s6 = Str("%1%2%3").arg(12.34f, -8, 'g', -1, '#').arg(123.45f, -8, 'g', -1, '#').arg(34.56f, -8);
// s6 == "12.34###123.45##34.56 "
cee::Str cee::Str::arg ( double  a,
int  fieldWidth = 0,
char  format = 'g',
int  precision = -1,
char  fillChar = ' ' 
) const

Returns a copy of this string with the lowest numbered place marker (e.g. %1, %2,..%99) replaced by the double a.

Parameters
aThe double value to insert at the lowest x
fieldWidthThe minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
format'g': default, 'e' : scientific notation (1.234e4). 'f' : Fixed notation (1234.0)
precisionThe precision for floating-point values. Only used for 'f' and 'e'
fillCharThe character that will be inserted if the string representation of a is shorter than the specified fieldWidth. If the length of a is shorter than fieldWidth, the string will be padded with this character.

This method searches the current string for the lowest x value, and then replaces all of the lowest occurrence with the passed data. Example of use:

Str s6 = Str("%1%2%3").arg(12.34, -8, 'g', -1, '#').arg(123.45, -8, 'g', -1, '#').arg(34.56, -8);
// s6 == "12.34###123.45##34.56 ");
const wchar_t * cee::Str::c_str ( ) const

Returns a null-terminated sequence of wchar_t characters.

size_t cee::Str::find ( const Str str,
size_t  start = 0 
) const

Returns the position of the first occurrence of str starting from start.

Returns Str::npos if not found

Str cee::Str::fromUnspecifiedWCharPointer ( const void *  voidPtr)
static

Constructs a new Str object from an unspecified const pointer to raw wchar_t data.

It is assumed that the data pointed to by voidPtr is actually a wchar_t*.

Warning
This function is exposed to aid in implementing conversion functions between string representations in different application frameworks, notably on Win32 platforms where wchar_t isn't always a built-in type. It should be used with care since it exposes the internal data structure.
bool cee::Str::isEmpty ( ) const

Returns true if the string has no characters, otherwise returns false.

bool cee::Str::matches ( const Str wildcard) const

Returns true if this string matches the given wildcard.

cee::Str cee::Str::number ( int  n)
static

Creates a string from the given integer.

cee::Str cee::Str::number ( unsigned int  n)
static

Creates a string from the given unsigned integer.

cee::Str cee::Str::number ( float  n,
char  format = 'g',
int  precision = -1 
)
static

Converts the given number to a string with the specified format.

Parameters
nThe number to convert
format'g': default, 'e' : scientific notation (1.234e4). 'f' : Fixed notation (1234.0)
precisionThe precision for floating-point values. Only used for 'f' and 'e'
Returns
A string with the given number
cee::Str cee::Str::number ( double  n,
char  format = 'g',
int  precision = -1 
)
static

Converts the given number to a string with the specified format.

Parameters
nThe number to convert
format'g': default, 'e' : scientific notation (1.234e4). 'f' : Fixed notation (1234.0)
precisionThe precision for floating-point values. Only used for 'f' and 'e'
Returns
A string with the given number
cee::Str cee::Str::numberFromAddress ( const void *  ptr)
static

Returns a string that is a textual representation of the pointer address.

bool cee::Str::operator!= ( const Str rhs) const

Returns true if this string is not equal to the passed string.

const Str cee::Str::operator+ ( const Str rhs) const

Returns the concatenation of this string and the passed rhs string.

Str & cee::Str::operator+= ( const Str rhs)

Sets this string to the concatenation of this string and the passed rhs string.

bool cee::Str::operator< ( const Str rhs) const

Returns true if this string is less than the passed string.

Str & cee::Str::operator= ( const Str other)

Assigns other to this string and returns a reference to this string.

bool cee::Str::operator== ( const Str rhs) const

Returns true if this string is equal to the passed string.

void cee::Str::replace ( const Str before,
const Str after 
)

Replaces occurrences of the string before with the string after.

cee::Str cee::Str::simplified ( ) const

Returns simplified string.

Strips leading and trailing whitespace. Replaces sequences of internal whitespace with one space

size_t cee::Str::size ( ) const

Returns the length of the string.

std::vector< Str > cee::Str::split ( const Str delimiters = " ") const

Splits the string into substrings wherever delimiters occurs, and returns the list of those strings.

Parameters
delimitersString containing characters used to split into token strings

If delimiters does not match anywhere in the string, split() returns a single-element list containing this string.

bool cee::Str::startsWith ( const Str str) const

Returns true if the string starts with the given str.

Same as: find(str) == 0

cee::Str cee::Str::subStr ( size_t  start,
size_t  length = npos 
) const

Returns the substring of the string starting with index start and the optional given length.

Parameters
startPosition of the first character to be copied as a substring. If this is equal to the string length, the function returns an empty string. If this is greater than the string length, it throws out_of_range. Note: The first character is denoted by a value of 0 (not 1).
lengthNumber of characters to include in the substring (if the string is shorter, as many characters as possible are used). A value of Str::npos indicates all characters until the end of the string.
void cee::Str::swap ( Str other)

Exchanges the contents of the two strings.

Parameters
otherModifiable reference to the string that should have its contents swapped.
Warning
Note that signature differs from normal Ceetron Desktop Components practice (passing non-const reference). This is done to be consistent with the signature of std::swap()
double cee::Str::toDouble ( bool *  ok = NULL) const

Converts the contents of the string to a double value (if possible)

Parameters
okIf not NULL, this will be set to true if conversion is ok, or to false if not
Returns
Returns the double value found at the start of the string. 0.0 if an error occurred.
double cee::Str::toDouble ( double  defaultValue) const

Converts the contents of the string to a double value (if possible)

Parameters
defaultValueThe value returned if the conversion failed.
Returns
Returns the double value found at the start of the string or defaultValue if the conversion was not possible.
float cee::Str::toFloat ( bool *  ok = NULL) const

Converts the contents of the string to a float value (if possible)

Parameters
okIf not NULL, this will be set to true if conversion is ok, or to false if not
Returns
Returns the float value found at the start of the string. 0.0f if an error occurred.
float cee::Str::toFloat ( float  defaultValue) const

Converts the contents of the string to a float value (if possible)

Parameters
defaultValueThe value returned if the conversion failed.
Returns
Returns the float value found at the start of the string or defaultValue if the conversion was not possible.
int cee::Str::toInt ( bool *  ok = NULL) const

Converts the contents of the string to a integer value (if possible)

Parameters
okIf not NULL, this will be set to true if conversion is ok, or to false if not
Returns
Returns the integer value found at the start of the string. 0 if an error occurred.
int cee::Str::toInt ( int  defaultValue) const

Converts the contents of the string to a integer value (if possible)

Parameters
defaultValueThe value returned if the conversion failed.
Returns
Returns the integer value found at the start of the string or defaultValue if the conversion was not possible.
cee::Str cee::Str::toLower ( ) const

Returns a lowercase copy of the string.

std::string cee::Str::toStdString ( ) const

Converts a string to an ascii std::string. Non-ascii characters are replaced by a question mark (?)

std::wstring cee::Str::toStdWString ( ) const

Converts a string to a std::wstring (std unicode string)

unsigned int cee::Str::toUInt ( bool *  ok = NULL) const

Converts the contents of the string to an unsigned integer value.

Parameters
okIf not NULL, this will be set to true if conversion is ok, or to false if not
Returns
Returns the unsigned integer value found at the start of the string. 0 if an error occurred.
unsigned int cee::Str::toUInt ( unsigned int  defaultValue) const

Converts the contents of the string to an unsigned integer value.

Parameters
defaultValueThe value returned if the conversion failed.
Returns
Returns the value found at the start of the string or defaultValue if the conversion was not possible.
cee::Str cee::Str::toUpper ( ) const

Returns an uppercase copy of the string.

std::string cee::Str::toUtf8 ( ) const

Converts a string to a Utf8 encoded string. Non-ascii characters are replaced by their multi-byte UTF8 encoding.

cee::Str cee::Str::trimmed ( ) const

Returns string with leading and trailing whitespace removed.

cee::Str cee::Str::trimmedLeft ( ) const

Returns string with leading whitespace removed.

cee::Str cee::Str::trimmedRight ( ) const

Returns string with trailing whitespace removed.

const void * cee::Str::unspecifiedWCharPointer ( ) const

Returns unspecified const pointer to the underlying raw wchar_t data array.

The actual data pointed to by the return value of this function is the same as that returned byt Str::c_str(), but without the type. It can be safely cast to const wchar_t*.

Warning
This function is exposed to aid in implementing conversion functions between string representations in different application frameworks, notably on Win32 platforms where wchar_t isn't always a built-in type. It should be used with care since it exposes the internal data structure.

Member Data Documentation

const size_t cee::Str::npos = static_cast<size_t>(-1)
static

Same as std::string::npos. This value, when used as the value for a count parameter n in string's member functions, roughly indicates "as many as possible". As a return value it is usually used to indicate failure.