cee::Str

class Str

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.

Public Functions

Str()

Constructs a string.

Str(const Str &other)

Constructs a string as a copy of other.

Str(const char *theString)

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

explicit Str(const wchar_t *theString)

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

explicit Str(const std::string &theString)

Creates a string from the given std::string.

explicit Str(const std::wstring &theString)

Creates a string from the given std::wstring.

explicit Str(char c)

Creates a string from the given char.

Str &operator=(const Str &other)

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

bool operator==(const Str &rhs) const

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

bool operator!=(const Str &rhs) const

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

bool operator<(const Str &rhs) const

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

const Str operator+(const Str &rhs) const

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

Str &operator+=(const Str &rhs)

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

Str toLower() const

Returns a lowercase copy of the string.

Str toUpper() const

Returns an uppercase copy of the string.

Str trimmedRight() const

Returns string with trailing whitespace removed.

Str trimmedLeft() const

Returns string with leading whitespace removed.

Str trimmed() const

Returns string with leading and trailing whitespace removed.

Str simplified() const

Returns simplified string.

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

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

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

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

Parameters:delimiters – String containing characters used to split into token strings
size_t 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

bool startsWith(const Str &str) const

Returns true if the string starts with the given str.

Same as: find(str) == 0

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:
  • start – Position 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).
  • length – Number 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 replace(const Str &before, const Str &after)

Replaces occurrences of the string before with the string after.

const wchar_t *c_str() const

Returns a null-terminated sequence of wchar_t characters.

std::string toStdString() const

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

std::wstring toStdWString() const

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

std::string toUtf8() const

Converts a string to a Utf8 encoded string.

Non-ascii characters are replaced by their multi-byte UTF8 encoding

bool isEmpty() const

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

size_t size() const

Returns the length of the string.

double toDouble(bool *ok = NULL) const

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

Parameters:ok – If 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 toDouble(double defaultValue) const

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

Parameters:defaultValue – The 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 toFloat(bool *ok = NULL) const

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

Parameters:ok – If 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 toFloat(float defaultValue) const

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

Parameters:defaultValue – The 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 toInt(bool *ok = NULL) const

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

Parameters:ok – If 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 toInt(int defaultValue) const

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

Parameters:defaultValue – The 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.
unsigned int toUInt(bool *ok = NULL) const

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

Parameters:ok – If 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 toUInt(unsigned int defaultValue) const

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

Parameters:defaultValue – The 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.
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.

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);

Parameters:
  • a – The string to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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.

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);

Parameters:
  • a – The character to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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.

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);

Parameters:
  • a – The int value to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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:
  • a – The value to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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.

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);

Parameters:
  • a – The unsigned int value to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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:
  • a – The value to insert at the lowest x
  • fieldWidth – The minimal number of characters the argument will occupy. Positive for right aligned text, negative for left aligned text.
  • fillChar – The 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.
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.

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   "

Parameters:
  • a – The float value to insert at the lowest x
  • fieldWidth – The 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)
  • precision – The precision for floating-point values. Only used for ‘f’ and ‘e’
  • fillChar – The 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.
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.

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   ");

Parameters:
  • a – The double value to insert at the lowest x
  • fieldWidth – The 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)
  • precision – The precision for floating-point values. Only used for ‘f’ and ‘e’
  • fillChar – The 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.
void swap(Str &other)

Exchanges the contents of the two strings.

Warning

Note that signature differs from normal CEETRON Envision practice (passing non-const reference). This is done to be consistent with the signature of std::swap()

Parameters:other – Modifiable reference to the string that should have its contents swapped.
bool matches(const Str &wildcard) const

Returns true if this string matches the given wildcard.

const void *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.

Public Static Functions

static Str number(int n)

Creates a string from the given integer.

static Str number(unsigned int n)

Creates a string from the given unsigned integer.

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

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

Parameters:
  • n – The number to convert
  • format – ‘g’: default, ‘e’: scientific notation (1.234e4). ‘f’: Fixed notation (1234.0)
  • precision – The precision for floating-point values. Only used for ‘f’ and ‘e’
Returns:

A string with the given number

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

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

Parameters:
  • n – The number to convert
  • format – ‘g’: default, ‘e’: scientific notation (1.234e4). ‘f’: Fixed notation (1234.0)
  • precision – The precision for floating-point values. Only used for ‘f’ and ‘e’
Returns:

A string with the given number

static Str numberFromAddress(const void *ptr)

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

static Str fromUnspecifiedWCharPointer(const void *voidPtr)

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.

static Str fromUtf8(const char *str)

Create a Str from an Utf8 encoded char* array.

Public Static 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.