Corrade::Utility::String namespace
#include <Corrade/Utility/String.h>

String utilities.

This library is built if CORRADE_WITH_UTILITY is enabled when building Corrade. To use this library with CMake, request the Utility component of the Corrade package and link to the Corrade::Utility target.

find_package(Corrade REQUIRED Utility)

# ...
target_link_libraries(your-app PRIVATE Corrade::Utility)

See also Downloading and building Corrade and Using Corrade with CMake for more information.

Functions

auto fromArray(const char* string) -> std::string
Safely construct string from char array.
auto fromArray(const char* string, std::size_t length) -> std::string
Safely construct string from char array with explicit length.
auto ltrim(std::string string, const std::string& characters) -> std::string
Trim leading characters from string.
template<std::size_t size>
auto ltrim(std::string string, const char(&characters)[size]) -> std::string
auto ltrim(std::string string) -> std::string
Trim leading whitespace from string.
auto rtrim(std::string string, const std::string& characters) -> std::string
Trim trailing characters from string.
template<std::size_t size>
auto rtrim(std::string string, const char(&characters)[size]) -> std::string
auto rtrim(std::string string) -> std::string
Trim trailing whitespace from string.
auto trim(std::string string, const std::string& characters) -> std::string
Trim leading and trailing characters from string.
template<std::size_t size>
auto trim(std::string string, const char(&characters)[size]) -> std::string
auto trim(std::string string) -> std::string
Trim leading and trailing whitespace from string.
void ltrimInPlace(std::string& string, const std::string& characters)
Trim leading characters from a string, in place.
template<std::size_t size>
void ltrimInPlace(std::string& string, const char(&characters)[size])
void ltrimInPlace(std::string& string)
Trim leading whitespace from a string, in place.
void rtrimInPlace(std::string& string, const std::string& characters)
Trim trailing characters from a string, in place.
template<std::size_t size>
void rtrimInPlace(std::string& string, const char(&characters)[size])
void rtrimInPlace(std::string& string)
Trim trailing whitespace from a string, in place.
void trimInPlace(std::string& string, const std::string& characters)
Trim leading and trailing characters from a string, in place.
template<std::size_t size>
void trimInPlace(std::string& string, const char(&characters)[size])
void trimInPlace(std::string& string)
Trim leading and trailing whitespace from a string, in place.
auto split(const std::string& string, char delimiter) -> std::vector<std::string>
Split a string on given character.
auto split(Containers::StringView string, char delimiter) -> Containers::Array<Containers::StringView> deprecated in Git master
auto splitWithoutEmptyParts(const std::string& string, char delimiter) -> std::vector<std::string>
Split a string on given character and remove empty parts.
auto splitWithoutEmptyParts(Containers::StringView string, char delimiter) -> Containers::Array<Containers::StringView> deprecated in Git master
auto splitWithoutEmptyParts(const std::string& string, const std::string& delimiters) -> std::vector<std::string>
Split a string on any character from given set and remove empty parts.
auto splitWithoutEmptyParts(Containers::StringView string, Containers::StringView delimiters) -> Containers::Array<Containers::StringView> deprecated in Git master
auto splitWithoutEmptyParts(const std::string& string) -> std::vector<std::string>
Split a string on whitespace and remove empty parts.
auto splitWithoutEmptyParts(const Containers::StringView string) -> Containers::Array<Containers::StringView> deprecated in Git master
auto partition(const std::string& string, char separator) -> Containers::StaticArray<3, std::string> new in 2019.10
Partition a string.
auto partition(const std::string& string, const std::string& separator) -> Containers::StaticArray<3, std::string> new in 2019.10
auto rpartition(const std::string& string, char separator) -> Containers::StaticArray<3, std::string> new in 2019.10
Right-partition a string.
auto rpartition(const std::string& string, const std::string& separator) -> Containers::StaticArray<3, std::string> new in 2019.10
auto join(const std::vector<std::string>& strings, char delimiter) -> std::string
Join strings with given character.
template<std::size_t size>
auto join(const std::vector<std::string>& strings, const char(&delimiter)[size]) -> std::string new in 2019.10
auto join(const std::vector<std::string>& strings, const std::string& delimiter) -> std::string new in 2019.10
auto joinWithoutEmptyParts(const std::vector<std::string>& strings, char delimiter) -> std::string
Join strings with given character and remove empty parts.
template<std::size_t size>
auto joinWithoutEmptyParts(const std::vector<std::string>& strings, const char(&delimiter)[size]) -> std::string
auto joinWithoutEmptyParts(const std::vector<std::string>& strings, const std::string& delimiter) -> std::string
void lowercaseInPlace(Containers::MutableStringView string) new in Git master
Convert ASCII characters in a string to lowercase, in place.
auto lowercase(Containers::StringView string) -> Containers::String new in Git master
Convert ASCII characters in a string to lowercase.
auto lowercase(Containers::String string) -> Containers::String new in Git master
auto lowercase(std::string string) -> std::string
void uppercaseInPlace(Containers::MutableStringView string) new in Git master
Convert ASCII characters in a string to uppercase, in place.
auto uppercase(Containers::StringView string) -> Containers::String new in Git master
Convert ASCII characters in a string to uppercase, in place.
auto uppercase(Containers::String string) -> Containers::String new in Git master
auto uppercase(std::string string) -> std::string
auto beginsWith(const std::string& string, const std::string& prefix) -> bool
Whether the string has given prefix.
template<std::size_t size>
auto beginsWith(const std::string& string, const char(&prefix)[size]) -> bool
auto beginsWith(const std::string& string, char prefix) -> bool
template<std::size_t size>
auto viewBeginsWith(Containers::ArrayView<const char> string, const char(&prefix)[size]) -> bool deprecated in Git master
Whether string view has given prefix.
auto viewBeginsWith(Containers::ArrayView<const char> string, char prefix) -> bool deprecated in Git master
auto endsWith(const std::string& string, const std::string& suffix) -> bool
Whether the string has given suffix.
template<std::size_t size>
auto endsWith(const std::string& string, const char(&suffix)[size]) -> bool
auto endsWith(const std::string& string, char suffix) -> bool
template<std::size_t size>
auto viewEndsWith(Containers::ArrayView<const char> string, const char(&suffix)[size]) -> bool deprecated in Git master
Whether string view has given suffix.
auto viewEndsWith(Containers::ArrayView<const char> string, char suffix) -> bool deprecated in Git master
auto stripPrefix(std::string string, const std::string& prefix) -> std::string
Strip given prefix from a string.
template<std::size_t size>
auto stripPrefix(std::string string, const char(&prefix)[size]) -> std::string
auto stripPrefix(std::string string, char prefix) -> std::string
auto stripSuffix(std::string string, const std::string& suffix) -> std::string
Strip given suffix from a string.
template<std::size_t size>
auto stripSuffix(std::string string, const char(&suffix)[size]) -> std::string
auto stripSuffix(std::string string, char suffix) -> std::string
auto replaceFirst(Containers::StringView string, Containers::StringView search, Containers::StringView replace) -> Containers::String new in Git master
Replace first occurrence in a string.
auto replaceAll(Containers::StringView string, Containers::StringView search, Containers::StringView replace) -> Containers::String new in Git master
Replace all occurrences in a string.
auto replaceAll(Containers::String string, char search, char replace) -> Containers::String new in Git master
Replace all occurrences of a character in a string with another character.
void replaceAllInPlace(Containers::MutableStringView string, char search, char replace) new in Git master
Replace all occurrences of a character in a string with another character in-place.
auto parseNumberSequence(Containers::StringView string, std::uint32_t min, std::uint32_t max) -> Containers::Optional<Containers::Array<std::uint32_t>> new in Git master
Parse a number sequence.

Function documentation

std::string Corrade::Utility::String::fromArray(const char* string)

Safely construct string from char array.

If string is nullptr, returns empty string.

std::string Corrade::Utility::String::fromArray(const char* string, std::size_t length)

Safely construct string from char array with explicit length.

If string is nullptr, returns empty string. Otherwise takes also length into account.

std::string Corrade::Utility::String::ltrim(std::string string, const std::string& characters)

Trim leading characters from string.

Parameters
string String to be trimmed
characters Characters which will be trimmed

Implemented using ltrimInPlace().

template<std::size_t size>
std::string Corrade::Utility::String::ltrim(std::string string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::ltrim(std::string string)

Trim leading whitespace from string.

Equivalent to calling ltrim(std::string, const char(&)[size]) with " \t\f\v\r\n" as second parameter. Implemented using ltrimInPlace().

std::string Corrade::Utility::String::rtrim(std::string string, const std::string& characters)

Trim trailing characters from string.

Parameters
string String to be trimmed
characters Characters which will be trimmed

Implemented using rtrimInPlace().

template<std::size_t size>
std::string Corrade::Utility::String::rtrim(std::string string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::rtrim(std::string string)

Trim trailing whitespace from string.

Equivalent to calling rtrim(std::string, const char(&)[size]) with " \t\f\v\r\n" as second parameter. Implemented using trimInPlace().

std::string Corrade::Utility::String::trim(std::string string, const std::string& characters)

Trim leading and trailing characters from string.

Parameters
string String to be trimmed
characters Characters which will be trimmed

Equivalent to ltrim(rtrim(string, characters), characters). Implemented using trimInPlace().

template<std::size_t size>
std::string Corrade::Utility::String::trim(std::string string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::trim(std::string string)

Trim leading and trailing whitespace from string.

Equivalent to calling trim(std::string, const char(&)[size]) with " \t\f\v\r\n" as second parameter. Implemented using trimInPlace().

void Corrade::Utility::String::ltrimInPlace(std::string& string, const std::string& characters)

Trim leading characters from a string, in place.

Parameters
string String to be trimmed in place
characters Characters which will be trimmed

template<std::size_t size>
void Corrade::Utility::String::ltrimInPlace(std::string& string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Corrade::Utility::String::ltrimInPlace(std::string& string)

Trim leading whitespace from a string, in place.

Equivalent to calling ltrimInPlace(std::string&, const char(&)[size]) with " \t\f\v\r\n" as second parameter.

void Corrade::Utility::String::rtrimInPlace(std::string& string, const std::string& characters)

Trim trailing characters from a string, in place.

Parameters
string String to be trimmed
characters Characters which will be trimmed

template<std::size_t size>
void Corrade::Utility::String::rtrimInPlace(std::string& string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Corrade::Utility::String::rtrimInPlace(std::string& string)

Trim trailing whitespace from a string, in place.

Equivalent to calling rtrimInPlace(std::string&, const char(&)[size]) with " \t\f\v\r\n" as second parameter.

void Corrade::Utility::String::trimInPlace(std::string& string, const std::string& characters)

Trim leading and trailing characters from a string, in place.

Parameters
string String to be trimmed
characters Characters which will be trimmed

Equivalent to calling both ltrimInPlace() and rtrimInPlace().

template<std::size_t size>
void Corrade::Utility::String::trimInPlace(std::string& string, const char(&characters)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Corrade::Utility::String::trimInPlace(std::string& string)

Trim leading and trailing whitespace from a string, in place.

Equivalent to calling trimInPlace(std::string&, const char(&)[size]) with " \t\f\v\r\n" as second parameter.

std::vector<std::string> Corrade::Utility::String::split(const std::string& string, char delimiter)

Split a string on given character.

Parameters
string String to split
delimiter Delimiter

Containers::Array<Containers::StringView> Corrade::Utility::String::split(Containers::StringView string, char delimiter)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::vector<std::string> Corrade::Utility::String::splitWithoutEmptyParts(const std::string& string, char delimiter)

Split a string on given character and remove empty parts.

Parameters
string String to split
delimiter Delimiter

Containers::Array<Containers::StringView> Corrade::Utility::String::splitWithoutEmptyParts(Containers::StringView string, char delimiter)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::vector<std::string> Corrade::Utility::String::splitWithoutEmptyParts(const std::string& string, const std::string& delimiters)

Split a string on any character from given set and remove empty parts.

Parameters
string String to split
delimiters Delimiter characters

Containers::Array<Containers::StringView> Corrade::Utility::String::splitWithoutEmptyParts(Containers::StringView string, Containers::StringView delimiters)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::vector<std::string> Corrade::Utility::String::splitWithoutEmptyParts(const std::string& string)

Split a string on whitespace and remove empty parts.

Equivalent to calling splitWithoutEmptyParts(const std::string&, const std::string&) with " \t\f\v\r\n" as second parameter.

Containers::Array<Containers::StringView> Corrade::Utility::String::splitWithoutEmptyParts(const Containers::StringView string)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Containers::StaticArray<3, std::string> Corrade::Utility::String::partition(const std::string& string, char separator) new in 2019.10

Partition a string.

Equivalent to Python's str.partition(). Splits string at the first occurrence of separator. First returned value is the part before the separator, second the separator, third a part after the separator. If the separator is not found, returns the input string followed by two empty strings.

Containers::StaticArray<3, std::string> Corrade::Utility::String::partition(const std::string& string, const std::string& separator) new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Containers::StaticArray<3, std::string> Corrade::Utility::String::rpartition(const std::string& string, char separator) new in 2019.10

Right-partition a string.

Equivalent to Python's str.rpartition(). Splits string at the last occurrence of separator. First returned value is the part before the separator, second the separator, third a part after the separator. If the separator is not found, returns two empty strings followed by the input string.

Containers::StaticArray<3, std::string> Corrade::Utility::String::rpartition(const std::string& string, const std::string& separator) new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::join(const std::vector<std::string>& strings, char delimiter)

Join strings with given character.

Parameters
strings Strings to join
delimiter Delimiter

template<std::size_t size>
std::string Corrade::Utility::String::join(const std::vector<std::string>& strings, const char(&delimiter)[size]) new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::join(const std::vector<std::string>& strings, const std::string& delimiter) new in 2019.10

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::joinWithoutEmptyParts(const std::vector<std::string>& strings, char delimiter)

Join strings with given character and remove empty parts.

Parameters
strings Strings to join
delimiter Delimiter

template<std::size_t size>
std::string Corrade::Utility::String::joinWithoutEmptyParts(const std::vector<std::string>& strings, const char(&delimiter)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::joinWithoutEmptyParts(const std::vector<std::string>& strings, const std::string& delimiter)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Corrade::Utility::String::lowercaseInPlace(Containers::MutableStringView string) new in Git master

Convert ASCII characters in a string to lowercase, in place.

Replaces any character from ABCDEFGHIJKLMNOPQRSTUVWXYZ with a corresponding character from abcdefghijklmnopqrstuvwxyz. Deliberately supports only ASCII as Unicode-aware case conversion is a much more complex topic.

Containers::String Corrade::Utility::String::lowercase(Containers::StringView string) new in Git master

Convert ASCII characters in a string to lowercase.

Allocates a copy and replaces any character from ABCDEFGHIJKLMNOPQRSTUVWXYZ with a corresponding character from abcdefghijklmnopqrstuvwxyz. Deliberately supports only ASCII as Unicode-aware case conversion is a much more complex topic.

Containers::String Corrade::Utility::String::lowercase(Containers::String string) new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Compared to lowercase(Containers::StringView) is able to perform the operation in-place if string is owned, transferring the data ownership to the returned instance. Makes a owned copy first if not.

std::string Corrade::Utility::String::lowercase(std::string string)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Corrade::Utility::String::uppercaseInPlace(Containers::MutableStringView string) new in Git master

Convert ASCII characters in a string to uppercase, in place.

Replaces any character from abcdefghijklmnopqrstuvwxyz with a corresponding character from ABCDEFGHIJKLMNOPQRSTUVWXYZ. Deliberately supports only ASCII as Unicode-aware case conversion is a much more complex topic.

Containers::String Corrade::Utility::String::uppercase(Containers::StringView string) new in Git master

Convert ASCII characters in a string to uppercase, in place.

Allocates a copy and replaces any character from abcdefghijklmnopqrstuvwxyz with a corresponding character from ABCDEFGHIJKLMNOPQRSTUVWXYZ. Deliberately supports only ASCII as Unicode-aware case conversion is a much more complex topic.

Containers::String Corrade::Utility::String::uppercase(Containers::String string) new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Compared to uppercase(Containers::StringView) is able to perform the operation in-place if string is owned, transferring the data ownership to the returned instance. Makes a owned copy first if not.

std::string Corrade::Utility::String::uppercase(std::string string)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Corrade::Utility::String::beginsWith(const std::string& string, const std::string& prefix)

Whether the string has given prefix.

In particular, returns true for empty string only if prefix is empty as well.

template<std::size_t size>
bool Corrade::Utility::String::beginsWith(const std::string& string, const char(&prefix)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Corrade::Utility::String::beginsWith(const std::string& string, char prefix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<std::size_t size>
bool Corrade::Utility::String::viewBeginsWith(Containers::ArrayView<const char> string, const char(&prefix)[size])

Whether string view has given prefix.

bool Corrade::Utility::String::viewBeginsWith(Containers::ArrayView<const char> string, char prefix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Corrade::Utility::String::endsWith(const std::string& string, const std::string& suffix)

Whether the string has given suffix.

In particular, returns true for empty string only if suffix is empty as well.

template<std::size_t size>
bool Corrade::Utility::String::endsWith(const std::string& string, const char(&suffix)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Corrade::Utility::String::endsWith(const std::string& string, char suffix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<std::size_t size>
bool Corrade::Utility::String::viewEndsWith(Containers::ArrayView<const char> string, const char(&suffix)[size])

Whether string view has given suffix.

bool Corrade::Utility::String::viewEndsWith(Containers::ArrayView<const char> string, char suffix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::stripPrefix(std::string string, const std::string& prefix)

Strip given prefix from a string.

Expects that the string actually begins with given prefix.

template<std::size_t size>
std::string Corrade::Utility::String::stripPrefix(std::string string, const char(&prefix)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::stripPrefix(std::string string, char prefix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::stripSuffix(std::string string, const std::string& suffix)

Strip given suffix from a string.

Expects that the string actually ends with given suffix.

template<std::size_t size>
std::string Corrade::Utility::String::stripSuffix(std::string string, const char(&suffix)[size])

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

std::string Corrade::Utility::String::stripSuffix(std::string string, char suffix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Containers::String Corrade::Utility::String::replaceFirst(Containers::StringView string, Containers::StringView search, Containers::StringView replace) new in Git master

Replace first occurrence in a string.

Returns string unmodified if it doesn't contain search. Having empty search causes replace to be prepended to string.

Containers::String Corrade::Utility::String::replaceAll(Containers::StringView string, Containers::StringView search, Containers::StringView replace) new in Git master

Replace all occurrences in a string.

Returns string unmodified if it doesn't contain search. Expects that search is not empty, as that would cause an infinite loop. For substituting a single character with another the replaceAll(Containers::String, char, char) variant is more optimal.

Containers::String Corrade::Utility::String::replaceAll(Containers::String string, char search, char replace) new in Git master

Replace all occurrences of a character in a string with another character.

The string is passed through unmodified if it doesn't contain search. Otherwise the operation is performed in-place if string is owned, transferring the data ownership to the returned instance. An owned copy is made if not. See also replaceAllInPlace() for a variant that operates on string views.

void Corrade::Utility::String::replaceAllInPlace(Containers::MutableStringView string, char search, char replace) new in Git master

Replace all occurrences of a character in a string with another character in-place.

Containers::Optional<Containers::Array<std::uint32_t>> Corrade::Utility::String::parseNumberSequence(Containers::StringView string, std::uint32_t min, std::uint32_t max) new in Git master

Parse a number sequence.

Parses a string containing a sequence of numbers, returning them converted to integers. The numbers can be delimited by commas (,), semicolons (;) or an arbitrary whitespace character. Order in which the numbers were specified is kept in the output including possible duplicates. Empty string results in an empty array returned.

Additionally it's possible to specify a range using the - character, in which case the range will be expanded in the output. The range is inclusive, meaning 3-6 will result in {3, 4, 5, 6} in the output. Ranges where the end is smaller than the start (such as 6-3) will be treated as empty. If the number before the - is omitted, a min is used instead; if the number after the - is omitted, max - 1 is used instead.

If an unrecognized character is encountered, the function prints an error and returns a Containers::NullOpt. If any parsed number is less than min, greater than or equal to max or doesn't fit into 32 bits, it's omitted in the output.

Example usage:

  • 4,3 5;5;17 results in {4, 3, 5, 5, 17}
  • 12-,3-5,1 with max set to 15 results in {12, 13, 14, 3, 4, 5, 1}
  • -3, 13- with min set to 0 and max to 15 results in {0, 1, 2, 3, 13, 14}
  • any input with min set to 0 and max set to 0 results in an empty output
  • - results in a range from min to max - 1