# 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 HOOPS 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.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...