Corrade::Containers::String class new in Git master
#include <Corrade/Containers/String.h>

String.

A lightweight non-templated alternative to std::string with support for custom deleters. A non-owning version of this container is a StringView and a MutableStringView, implemented using a generic BasicStringView.

Usage

It's recommended to prefer using StringView / MutableStringView in most cases, and only create a String instance if you need to extend lifetime of the data or perform an operation that can't be done by mutating a view in-place. The String is implicitly convertible from C string literals, but the designated way to instantiate a string is using the operator""_s() literal. While both expressions are mostly equivalent, the implicit conversion has some runtime impact due to std::strlen(), and it won't preserve zero bytes inside the string:

Containers::String a = "hello\0world!";         // a.size() == 5
Containers::String b = "hello\0world!"_s;       // a.size() == 12

The String class provides access, slicing and lookup APIs similar to StringView, see its usage docs for details. All String slicing APIs return a (mutable) StringView, additionally String instances are implicitly convertible from and to (mutable) StringView. All instances (including an empty string) are guaranteed to be null-terminated, which means a conversion to StringView will always have StringViewFlag::NullTerminated set.

As with StringView, the class is implicitly convertible to ArrayView. In addition it's also move-convertible to Array, transferring the ownership of the internal data array to it. Ownership transfer in the other direction is not provided because it's not possible to implicitly guarantee null termination of the input Array. In that case use the explicit String(char*, std::size_t, Deleter) constructor together with Array::release() and Array::deleter(). See also Wrapping externally allocated strings below.

Small string optimization

The class stores data size, data pointer and a deleter pointer, which is 24 bytes on 64-bit platforms (and 12 bytes on 32-bit). To avoid allocations for small strings, small strings up to 22 bytes on 64-bit (23 including the null terminator) and up to 10 bytes on 32-bit (11 including the null terminator) are by default stored inside the class.

Such optimization is completely transparent to the user, the only difference is that deleter() and release() can't be called on SSO strings, as there is nothing to delete / release. Presence of SSO on an instance can be queried using isSmall().

In cases where SSO isn't desired — for example when strings are stored in a growable array, are externally referenced via StringView instances or char* and pointer stability is required after a reallocation — the string can be constructed with String(AllocatedInitT, const char*) and related APIs using the AllocatedInit tag, which bypasses this optimization and always allocates. This property is then also preserved on all moves and copies regardless of the actual string size, i.e., small strings don't suddenly become SSO instances if the growable array gets reallocated. An AllocatedInit small string can be turned into an SSO instance again by explicitly using the String(StringView) constructor:

Containers::String a{Containers::AllocatedInit, "hi!"}; // a.isSmall() == false
Containers::String b = std::move(a);                    // b.isSmall() == false
Containers::String c = b;                               // c.isSmall() == false

Containers::String d = Containers::StringView{c};       // d.isSmall() == true

String initialization

In addition to creating a String from an existing string (literal) or wrapping an externally allocated memory as mentioned above, explicit initialization constructors are provided, similarly to the Array class:

  • String(ValueInitT, std::size_t) zero-initializes the string, meaning each of its characters is '\0'. For heap-allocated strings this is equivalent to new char[size + 1]{} (the one extra character is for the null terminator).
  • String(DirectInitT, std::size_t, char) fills the whole string with given character and zero-initializes the null terminator. For heap-allocated strings this is equivalent to new char[size + 1]{c, c, c, …, '\0'}.
  • String(NoInitT, std::size_t) keeps the contents uninitialized, except for the null terminator. Equivalent to new char[size + 1] followed by string[size] = '\0'.

Unlike an Array, there's no DefaultInitT constructor, as the same behavior is already provided by String(NoInitT, std::size_t).

Wrapping externally allocated strings

Similarly to Array, by default the class makes all allocations using operator new[] and deallocates using operator delete[]. It's however also possible to wrap an externally allocated string using String(char*, std::size_t, Deleter) together with specifying which function to use for deallocation.

For example, properly deallocating a string allocated using std::malloc():

{
    /* Extra space for a null terminator */
    char* data = reinterpret_cast<char*>(std::malloc(size + 1));

    // Will call std::free() on destruction
    Containers::String string{data, size,
        [](char* data, std::size_t) { std::free(data); }};
}

Converting String instances to null-terminated C strings

If possible when interacting with 3rd party APIs, passing a string together with the size information is always preferable to passing just a plain const char*. Apart from saving an unnecessary std::strlen() call it can avoid unbounded memory reads in security-critical scenarios.

As said above, a String is guaranteed to always be null-terminated, even in case it's empty. However, unlike with Array, there's no implicit conversion to const char*, because the string can still contain a '\0' anywhere in the middle — thus you have to get the pointer explicitly using data(). In case your string can contain null bytes, you should only pass it together with size() or as a range of pointers using begin() and end() instead, assuming the target API supports such input.

Extra attention is needed when the originating String instance can move after the C string pointer got stored somewhere. Pointers to heap-allocated strings will not get invalidated but SSO strings will, leading to nasty crashes when accessing the original pointer. Apart from ensuring the instances won't get moved, another solution is to force the strings to be always allocated with String(AllocatedInitT, String&&) and other variants using the AllocatedInit tag. For example:

void exec(int argc, const char** argv);

Containers::Array<Containers::String> data;
Containers::Array<const char*> argv;
while(hasNextArg()) {
    /* If arrayAppend(storage, nextArgument()) was used, the data() passed to
       argv could be invalidated next time the storage gets reallocated */
    arrayAppend(data, Containers::String{Containers::AllocatedInit, nextArg()});
    arrayAppend(argv, data.back().data());
}

exec(argv.size(), argv.data());

See also Converting StringView instances to null-terminated C strings.

STL compatibility

Instances of String are implicitly convertible from and to std::string if you include Corrade/Containers/StringStl.h. The conversion is provided in a separate header to avoid unconditional #include <string>, which significantly affects compile times. The following table lists allowed conversions:

Corrade type↭STL type
String⇆std::string (data copy)

Example:

#include <Corrade/Containers/StringStl.h>

…

std::string a = "Hello world!";
Containers::String b = a.substr(5);

Because std::string doesn't provide any way to transfer ownership of its underlying memory, conversion either way always involves a data copy. To mitigate the conversion impact, it's recommended to convert std::string instances to StringView instead where possible.

On compilers that support C++17 and std::string_view, implicit conversion from and to it is provided in Corrade/Containers/StringStlView.h. For similar reasons, it's a dedicated header to avoid unconditional #include <string_view>, but this one is even significantly heavier than the <string> include on certain implementations, so it's separate from a std::string as well. The following table lists allowed conversions:

Corrade type↭STL type
String←std::string_view (data copy)
String→std::string_view

Example:

#include <Corrade/Containers/StringStlView.h>

…

std::string_view a = "Hello world!";
Containers::String b = a.substr(5);

The std::string_view type doesn't have any mutable counterpart, so there's no differentiation for a const variant. While creating a std::string_view from a String creates a non-owning reference without allocations or copies, converting the other way involves a data copy. To mitigate the conversion impact, it's recommended to convert std::string_view instances to StringView instead where possible.

Finally, the Corrade/Containers/StringStlHash.h header provides a std::hash specialization for String, making it usable in std::unordered_map and std::unordered_set. It's also separate, due to dependency on #include <functional> which is among the heaviest STL headers in existence, and which is only really needed when you deal with unordered containers.

Public types

using Deleter = void(*)(char*, std::size_t)
Deleter type.

Public static functions

static auto nullTerminatedView(StringView view) -> String
Turn a view into a null-terminated string.
static auto nullTerminatedView(AllocatedInitT, StringView view) -> String
Turn a view into a null-terminated string, bypassing SSO.
static auto nullTerminatedGlobalView(StringView view) -> String
Turn a view into a null-terminated global string.
static auto nullTerminatedGlobalView(AllocatedInitT, StringView view) -> String
Turn a view into a null-terminated global string, bypassing SSO.

Constructors, destructors, conversion operators

String() noexcept
Default constructor.
String(StringView view)
Construct from a string view.
String(ArrayView<const char> view)
String(MutableStringView view)
String(ArrayView<char> view)
String(const char* data)
Construct from a null-terminated C string.
String(const char* data, std::size_t size)
Construct from a sized C string.
String(AllocatedInitT, StringView view) explicit
Construct from a string view, bypassing SSO.
String(AllocatedInitT, ArrayView<const char> view) explicit
String(AllocatedInitT, MutableStringView view) explicit
String(AllocatedInitT, ArrayView<char> view) explicit
String(AllocatedInitT, String&& other) explicit
Create a string instance bypassing SSO.
String(AllocatedInitT, const String& other) explicit
String(AllocatedInitT, const char* data) explicit
Construct from a null-terminated C string, bypassing SSO.
String(AllocatedInitT, const char* data, std::size_t size) explicit
Construct from a sized C string.
String(char* data, std::size_t size, Deleter deleter) explicit noexcept
Take ownership of an external data array.
String(char* data, Deleter deleter) explicit noexcept
Take ownership of an external data array with implicit size.
String(const char* data, std::size_t size, Deleter deleter) explicit noexcept
Take ownership of an immutable external data array.
String(const char* data, Deleter deleter) explicit noexcept
Take ownership of an external data array with implicit size.
String(std::nullptr_t, std::size_t size, Deleter deleter) deleted explicit
Taking ownership of a null pointer is not allowed.
String(std::nullptr_t, Deleter deleter) deleted explicit
Taking ownership of a null pointer is not allowed.
String(Corrade::ValueInitT, std::size_t size) explicit
Create a zero-initialized string.
String(Corrade::NoInitT, std::size_t size) explicit
Create an uninitialized string.
String(Corrade::DirectInitT, std::size_t size, char c) explicit
Create a string initialized to a particular character.
template<class T, class = decltype(Implementation::StringConverter<typename std::decay<T && >::type>::from(std::declval<T && >()))>
String(T&& other) noexcept
Construct a view on an external type / from an external representation.
~String()
Destructor.
String(const String& other)
Copy constructor.
String(String&& other) noexcept
Move constructor.
operator ArrayView<const char>() const noexcept
Convert to a const ArrayView.
operator ArrayView<const void>() const noexcept
operator ArrayView<char>() noexcept
Convert to an ArrayView.
operator ArrayView<void>() noexcept
operator Array<char>() &&
Move-convert to an Array.
template<class T, class = decltype(Implementation::StringConverter<T>::to(std::declval<String>()))>
operator T() const
Convert the string to external representation.
operator bool() const explicit
Whether the string is non-empty.

Public functions

auto operator=(const String& other) -> String&
Copy assignment.
auto operator=(String&& other) -> String& noexcept
Move assignment.
auto isSmall() const -> bool
Whether the string is stored using small string optimization.
auto viewFlags() const -> StringViewFlags
View flags.
auto data() -> char*
String data.
auto data() const -> const char*
auto deleter() const -> Deleter
String deleter.
auto isEmpty() const -> bool
Whether the string is empty.
auto size() const -> std::size_t
String size.
auto begin() -> char*
Pointer to the first byte.
auto begin() const -> const char*
auto cbegin() const -> const char*
auto end() -> char*
Pointer to (one item after) the last byte.
auto end() const -> const char*
auto cend() const -> const char*
auto front() -> char&
First byte.
auto front() const -> char
auto back() -> char&
Last byte.
auto back() const -> char
auto operator[](std::size_t i) -> char&
Element access.
auto operator[](std::size_t i) const -> char
auto slice(char* begin, char* end) -> MutableStringView
View on a slice.
auto slice(const char* begin, const char* end) const -> StringView
auto slice(std::size_t begin, std::size_t end) -> MutableStringView
auto slice(std::size_t begin, std::size_t end) const -> StringView
auto sliceSize(char* begin, std::size_t size) -> MutableStringView
View on a slice of given size.
auto sliceSize(const char* begin, std::size_t size) const -> StringView
auto sliceSize(std::size_t begin, std::size_t size) -> MutableStringView
auto sliceSize(std::size_t begin, std::size_t size) const -> StringView
auto prefix(char* end) -> MutableStringView
View on a prefix until a pointer.
auto prefix(const char* end) const -> StringView
auto suffix(char* begin) -> MutableStringView
View on a suffix after a pointer.
auto suffix(const char* begin) const -> StringView
auto prefix(std::size_t size) -> MutableStringView
View on the first size bytes.
auto prefix(std::size_t size) const -> StringView
auto exceptPrefix(std::size_t size) -> MutableStringView
View except the first size bytes.
auto exceptPrefix(std::size_t size) const -> StringView
auto suffix(std::size_t begin) -> MutableStringView deprecated in Git master
View except the first size bytes.
auto suffix(std::size_t begin) const -> StringView deprecated in Git master
View except the first size bytes.
auto exceptSuffix(std::size_t size) -> MutableStringView
View except the last size bytes.
auto exceptSuffix(std::size_t size) const -> StringView
auto except(std::size_t count) -> MutableStringView deprecated in Git master
View except the last size bytes.
auto except(std::size_t count) const -> StringView deprecated in Git master
auto split(char delimiter) -> Array<MutableStringView>
Split on given character.
auto split(char delimiter) const -> Array<StringView>
auto split(StringView delimiter) -> Array<MutableStringView>
Split on given substring.
auto split(StringView delimiter) const -> Array<StringView>
auto splitWithoutEmptyParts(char delimiter) -> Array<MutableStringView>
Split on given character, removing empty parts.
auto splitWithoutEmptyParts(char delimiter) const -> Array<StringView>
auto splitOnAnyWithoutEmptyParts(StringView delimiters) -> Array<MutableStringView>
Split on any character from given set, removing empty parts.
auto splitOnAnyWithoutEmptyParts(StringView delimiters) const -> Array<StringView>
auto splitWithoutEmptyParts(StringView delimiters) -> Array<MutableStringView> deprecated in Git master
Split on any character from given set, removing empty parts.
auto splitWithoutEmptyParts(StringView delimiters) const -> Array<StringView> deprecated in Git master
auto splitOnWhitespaceWithoutEmptyParts() -> Array<MutableStringView>
Split on whitespace, removing empty parts.
auto splitOnWhitespaceWithoutEmptyParts() const -> Array<StringView>
auto splitWithoutEmptyParts() -> Array<MutableStringView> deprecated in Git master
Split on whitespace, removing empty parts.
auto splitWithoutEmptyParts() const -> Array<StringView> deprecated in Git master
auto partition(char separator) -> Array3<MutableStringView>
Partition on a character.
auto partition(char separator) const -> Array3<StringView>
auto partition(StringView separator) -> Array3<MutableStringView>
Partition on a substring.
auto partition(StringView separator) const -> Array3<StringView>
auto partitionLast(char separator) -> Array3<MutableStringView>
Partition on a last occurence of a character.
auto partitionLast(char separator) const -> Array3<StringView>
auto partitionLast(StringView separator) -> Array3<MutableStringView>
Partition on a last occurence of a substring.
auto partitionLast(StringView separator) const -> Array3<StringView>
auto join(const StringIterable& strings) const -> String
Join strings with this view as the delimiter.
auto joinWithoutEmptyParts(const StringIterable& strings) const -> String
Join strings with this view as the delimiter, skipping empty parts.
auto hasPrefix(StringView prefix) const -> bool
Whether the string begins with given prefix.
auto hasPrefix(char prefix) const -> bool
auto hasSuffix(StringView suffix) const -> bool
Whether the string ends with given suffix.
auto hasSuffix(char suffix) const -> bool
auto exceptPrefix(StringView prefix) -> MutableStringView
View with given prefix stripped.
auto exceptPrefix(StringView prefix) const -> StringView
auto exceptPrefix(char prefix) -> MutableStringView deleted
Using char literals for prefix stripping is not allowed.
auto exceptPrefix(char prefix) const -> StringView deleted
auto stripPrefix(StringView prefix) -> MutableStringView deprecated in Git master
View except the first size bytes.
auto stripPrefix(StringView prefix) const -> StringView deprecated in Git master
View except the first size bytes.
auto exceptSuffix(StringView suffix) -> MutableStringView
View with given suffix stripped.
auto exceptSuffix(StringView suffix) const -> StringView
auto exceptSuffix(char suffix) -> MutableStringView deleted
Using char literals for suffix stripping is not allowed.
auto exceptSuffix(char suffix) const -> StringView deleted
auto stripSuffix(StringView suffix) -> MutableStringView deprecated in Git master
View except the last size bytes.
auto stripSuffix(StringView suffix) const -> StringView deprecated in Git master
View except the last size bytes.
auto trimmed(StringView characters) -> MutableStringView
View with given characters trimmed from prefix and suffix.
auto trimmed(StringView characters) const -> StringView
auto trimmed() -> MutableStringView
View with whitespace trimmed from prefix and suffix.
auto trimmed() const -> StringView
auto trimmedPrefix(StringView characters) -> MutableStringView
View with given characters trimmed from prefix.
auto trimmedPrefix(StringView characters) const -> StringView
auto trimmedPrefix() -> MutableStringView
View with whitespace trimmed from prefix.
auto trimmedPrefix() const -> StringView
auto trimmedSuffix(StringView characters) -> MutableStringView
View with given characters trimmed from suffix.
auto trimmedSuffix(StringView characters) const -> StringView
auto trimmedSuffix() -> MutableStringView
View with whitespace trimmed from suffix.
auto trimmedSuffix() const -> StringView
auto find(StringView substring) -> MutableStringView
Find a substring.
auto find(StringView substring) const -> StringView
auto find(char character) -> MutableStringView
Find a substring.
auto find(char character) const -> StringView
auto findOr(StringView substring, char* fail) -> MutableStringView
Find a substring with a custom failure pointer.
auto findOr(StringView substring, const char* fail) const -> StringView
auto findOr(char character, char* fail) -> MutableStringView
Find a substring with a custom failure pointer.
auto findOr(char character, const char* fail) const -> StringView
auto findLast(StringView substring) -> MutableStringView
Find the last occurence of a substring.
auto findLast(StringView substring) const -> StringView
auto findLast(char character) -> MutableStringView
Find the last occurence of a substring.
auto findLast(char character) const -> StringView
auto findLastOr(StringView substring, char* fail) -> MutableStringView
Find the last occurence of a substring with a custom failure pointer.
auto findLastOr(StringView substring, const char* fail) const -> StringView
auto findLastOr(char character, char* fail) -> MutableStringView
Find the last occurence of a substring with a custom failure pointer.
auto findLastOr(char character, const char* fail) const -> StringView
auto contains(StringView substring) const -> bool
Whether the string contains a substring.
auto contains(char character) const -> bool
Whether the string contains a character.
auto findAny(StringView characters) -> MutableStringView
Find any character from given set.
auto findAny(StringView characters) const -> StringView
auto findAnyOr(StringView characters, char* fail) -> MutableStringView
Find any character from given set with a custom failure pointer.
auto findAnyOr(StringView characters, const char* fail) const -> StringView
auto findLastAny(StringView characters) -> MutableStringView
Find the last occurence of any character from given set.
auto findLastAny(StringView characters) const -> StringView
auto findLastAnyOr(StringView characters, char* fail) -> MutableStringView
Find the last occurence of any character from given set with a custom failure pointer.
auto findLastAnyOr(StringView characters, const char* fail) const -> StringView
auto containsAny(StringView substring) const -> bool
Whether the string contains any character from given set.
auto release() -> char*
Release data storage.

Function documentation

static String Corrade::Containers::String::nullTerminatedView(StringView view)

Turn a view into a null-terminated string.

If the view is StringViewFlag::NullTerminated, returns a non-owning reference to it without any extra allocations or copies involved, propagating also StringViewFlag::Global to viewFlags() if present. Otherwise creates a null-terminated owning copy using String(StringView).

This function is primarily meant for efficiently passing StringView instances to APIs that expect null-terminated const char*. Mutating the result in any way is undefined behavior.

static String Corrade::Containers::String::nullTerminatedView(AllocatedInitT, StringView view)

Turn a view into a null-terminated string, bypassing SSO.

Compared to nullTerminatedView(StringView) the null-terminated copy is always allocated.

static String Corrade::Containers::String::nullTerminatedGlobalView(StringView view)

Turn a view into a null-terminated global string.

If the view is both StringViewFlag::NullTerminated and StringViewFlag::Global, returns a non-owning reference to it without any extra allocations or copies involved, propagating also StringViewFlag::Global to viewFlags(). Otherwise creates a null-terminated owning copy using String(StringView).

This function is primarily meant for efficiently storing StringView instances, ensuring the memory stays in scope and then passing them to APIs that expect null-terminated const char*. Mutating the result in any way is undefined behavior.

static String Corrade::Containers::String::nullTerminatedGlobalView(AllocatedInitT, StringView view)

Turn a view into a null-terminated global string, bypassing SSO.

Compared to nullTerminatedGlobalView(StringView) the null-terminated copy is always allocated.

Corrade::Containers::String::String() noexcept

Default constructor.

Creates an empty string.

Corrade::Containers::String::String(StringView view)

Construct from a string view.

Creates a null-terminated owning copy of view. Contrary to the behavior of std::string, view is allowed to be nullptr, but only if it's size is zero. Depending on the size, it's either stored allocated or in a SSO.

Corrade::Containers::String::String(ArrayView<const char> view)

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

Corrade::Containers::String::String(MutableStringView view)

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

Corrade::Containers::String::String(ArrayView<char> view)

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

Corrade::Containers::String::String(const char* data)

Construct from a null-terminated C string.

Creates a null-terminated owning copy of data. Contrary to the behavior of std::string, data is allowed to be nullptr — in that case an empty string is constructed. Depending on the size, it's either stored allocated or in a SSO.

Corrade::Containers::String::String(const char* data, std::size_t size)

Construct from a sized C string.

Creates a null-terminated owning copy of data. Contrary to the behavior of std::string, data is allowed to be nullptr, but only if size is zero. Depending on the size, it's either stored allocated or in a SSO.

Corrade::Containers::String::String(AllocatedInitT, StringView view) explicit

Construct from a string view, bypassing SSO.

Compared to String(StringView) the data is always allocated.

Corrade::Containers::String::String(AllocatedInitT, ArrayView<const char> view) explicit

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

Corrade::Containers::String::String(AllocatedInitT, MutableStringView view) explicit

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

Corrade::Containers::String::String(AllocatedInitT, ArrayView<char> view) explicit

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

Corrade::Containers::String::String(AllocatedInitT, String&& other) explicit

Create a string instance bypassing SSO.

If other already has allocated data, the data ownership is transferred. Otherwise a copy is allocated.

Corrade::Containers::String::String(AllocatedInitT, const String& other) explicit

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

Corrade::Containers::String::String(AllocatedInitT, const char* data) explicit

Construct from a null-terminated C string, bypassing SSO.

Compared to String(const char*) the data is always allocated.

Corrade::Containers::String::String(AllocatedInitT, const char* data, std::size_t size) explicit

Construct from a sized C string.

Compared to String(const char*, std::size_t) the data is always allocated.

Corrade::Containers::String::String(char* data, std::size_t size, Deleter deleter) explicit noexcept

Take ownership of an external data array.

Parameters
data String. Can't be nullptr.
size Size of the string, excluding the null terminator
deleter Deleter. Use nullptr for the standard delete[].

Since the String class provides a guarantee of null-terminated strings, the data array is expected to be null-terminated (which implies data can't be nullptr), but the null terminator not being included in size. For consistency and interoperability with Array (i.e., an empty string turning to a zero-sized array) this in turn means the size passed to deleter is one byte less than the actual memory size, and if the deleter does sized deallocation, it has to account for that.

The deleter will be unconditionally called on destruction with data and size as an argument. In particular, it will be also called if size is 0 (data isn't allowed to be nullptr).

In case of a moved-out instance, the deleter gets reset to a default-constructed value alongside the array pointer and size. It effectively means delete[] nullptr gets called when destructing a moved-out instance (which is a no-op).

Corrade::Containers::String::String(char* data, Deleter deleter) explicit noexcept

Take ownership of an external data array with implicit size.

Calculates the size using std::strlen() and calls String(char*, std::size_t, Deleter).

Corrade::Containers::String::String(const char* data, std::size_t size, Deleter deleter) explicit noexcept

Take ownership of an immutable external data array.

Casts away the const and delegates to String(char*, std::size_t, Deleter). This constructor is provided mainly to allow a String instance to reference global immutable data (such as C string literals) without having to make a copy, it's the user responsibility to avoid mutating the data in any way.

Corrade::Containers::String::String(const char* data, Deleter deleter) explicit noexcept

Take ownership of an external data array with implicit size.

Calculates the size using std::strlen() and calls String(const char*, std::size_t, Deleter).

Corrade::Containers::String::String(std::nullptr_t, std::size_t size, Deleter deleter) explicit deleted

Taking ownership of a null pointer is not allowed.

Since the String class provides a guarantee of null-terminated strings, data can't be nullptr.

Corrade::Containers::String::String(std::nullptr_t, Deleter deleter) explicit deleted

Taking ownership of a null pointer is not allowed.

Since the String class provides a guarantee of null-terminated strings, data can't be nullptr.

Corrade::Containers::String::String(Corrade::ValueInitT, std::size_t size) explicit

Create a zero-initialized string.

Parameters
size Size excluding the null terminator

Corrade::Containers::String::String(Corrade::NoInitT, std::size_t size) explicit

Create an uninitialized string.

Parameters
size Size excluding the null terminator

While the string contents are left untouched, the null terminator does get initialized to '\0'. Useful if you're going to overwrite the contents anyway.

Corrade::Containers::String::String(Corrade::DirectInitT, std::size_t size, char c) explicit

Create a string initialized to a particular character.

Parameters
size Size excluding the null terminator
c Character value

template<class T, class = decltype(Implementation::StringConverter<typename std::decay<T && >::type>::from(std::declval<T && >()))>
Corrade::Containers::String::String(T&& other) noexcept

Construct a view on an external type / from an external representation.

Corrade::Containers::String::~String()

Destructor.

Calls deleter() on the owned data(); in case of a SSO does nothing.

Corrade::Containers::String::String(const String& other)

Copy constructor.

If other is a SSO instance, the copy is as well, otherwise a copy is allocated using the default operator new[]. The actual string size isn't taken into account. See Small string optimization for more information.

Corrade::Containers::String::operator ArrayView<const char>() const noexcept

Convert to a const ArrayView.

The resulting view has the same size as this string size() — the null terminator is not counted into it.

Corrade::Containers::String::operator ArrayView<const void>() const noexcept

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

Corrade::Containers::String::operator ArrayView<char>() noexcept

Convert to an ArrayView.

The resulting view has the same size as this string size() — the null terminator is not counted into it. Note that with custom deleters the returned view is not guaranteed to be actually mutable.

Corrade::Containers::String::operator ArrayView<void>() noexcept

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

Corrade::Containers::String::operator Array<char>() &&

Move-convert to an Array.

The data and the corresponding deleter() is transferred to the returned array. In case of a SSO, a copy of the string is allocated and a default deleter is used. The string then resets data pointer, size and deleter to be equivalent to a default-constructed instance. In both the allocated and the SSO case the returned array contains a sentinel null terminator (i.e., not counted into its size). Note that with custom deleters the array is not guaranteed to be actually mutable.

template<class T, class = decltype(Implementation::StringConverter<T>::to(std::declval<String>()))>
Corrade::Containers::String::operator T() const

Convert the string to external representation.

Corrade::Containers::String::operator bool() const explicit

Whether the string is non-empty.

Returns true if the string is non-empty, false otherwise. Compared to BasicStringView::operator bool(), a String can never be nullptr, so the pointer value isn't taken into account here.

String& Corrade::Containers::String::operator=(const String& other)

Copy assignment.

If other is a SSO instance, the copy is as well, otherwise a copy is allocated using the default operator new[]. The actual string size isn't taken into account. See Small string optimization for more information.

bool Corrade::Containers::String::isSmall() const

Whether the string is stored using small string optimization.

It's not allowed to call deleter() or release() on a SSO instance. See Small string optimization for more information.

StringViewFlags Corrade::Containers::String::viewFlags() const

View flags.

A StringView constructed from this instance will have these flags. StringViewFlag::NullTerminated is present always, StringViewFlag::Global if the string was originally created from a global null-terminated view with nullTerminatedView() or nullTerminatedGlobalView().

char* Corrade::Containers::String::data()

String data.

The pointer is always guaranteed to be non-null and the data to be null-terminated, however note that the actual string might contain null bytes earlier than at the end.

const char* Corrade::Containers::String::data() const

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

Deleter Corrade::Containers::String::deleter() const

String deleter.

If set to nullptr, the contents are deleted using standard operator delete[]. Can be called only if the string is not stored using SSO — see Small string optimization for more information.

bool Corrade::Containers::String::isEmpty() const

Whether the string is empty.

std::size_t Corrade::Containers::String::size() const

String size.

Excludes the null terminator.

char* Corrade::Containers::String::begin()

Pointer to the first byte.

const char* Corrade::Containers::String::begin() const

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

const char* Corrade::Containers::String::cbegin() const

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

char* Corrade::Containers::String::end()

Pointer to (one item after) the last byte.

const char* Corrade::Containers::String::end() const

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

const char* Corrade::Containers::String::cend() const

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

char& Corrade::Containers::String::front()

First byte.

Expects there is at least one byte.

char Corrade::Containers::String::front() const

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

char& Corrade::Containers::String::back()

Last byte.

Expects there is at least one byte.

char Corrade::Containers::String::back() const

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

char& Corrade::Containers::String::operator[](std::size_t i)

Element access.

Expects that i is less than or equal to size().

char Corrade::Containers::String::operator[](std::size_t i) const

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

MutableStringView Corrade::Containers::String::slice(char* begin, char* end)

View on a slice.

Equivalent to BasicStringView::slice(). Both arguments are expected to be in range. If end points to (one item after) the end of the original (null-terminated) string, the result has StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::slice(const char* begin, const char* end) const

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

MutableStringView Corrade::Containers::String::slice(std::size_t begin, std::size_t end)

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

StringView Corrade::Containers::String::slice(std::size_t begin, std::size_t end) const

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

MutableStringView Corrade::Containers::String::sliceSize(char* begin, std::size_t size)

View on a slice of given size.

Equivalent to BasicStringView::sliceSize(). Both arguments are expected to be in range. If begin + size points to (one item after) the end of the original (null-terminated) string, the result has StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::sliceSize(const char* begin, std::size_t size) const

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

MutableStringView Corrade::Containers::String::sliceSize(std::size_t begin, std::size_t size)

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

StringView Corrade::Containers::String::sliceSize(std::size_t begin, std::size_t size) const

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

MutableStringView Corrade::Containers::String::prefix(char* end)

View on a prefix until a pointer.

Equivalent to BasicStringView::prefix(T*) const. If end points to (one item after) the end of the original (null-terminated) string, the result has StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::prefix(const char* end) const

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

MutableStringView Corrade::Containers::String::suffix(char* begin)

View on a suffix after a pointer.

Equivalent to BasicStringView::suffix(T*) const. The result has always StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::suffix(const char* begin) const

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

MutableStringView Corrade::Containers::String::prefix(std::size_t size)

View on the first size bytes.

Equivalent to BasicStringView::prefix(std::size_t) const. If size is equal to size(), the result has StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::prefix(std::size_t size) const

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

MutableStringView Corrade::Containers::String::exceptPrefix(std::size_t size)

View except the first size bytes.

Equivalent to BasicStringView::exceptPrefix(). The result has always StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::exceptPrefix(std::size_t size) const

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

MutableStringView Corrade::Containers::String::suffix(std::size_t begin)

View except the first size bytes.

StringView Corrade::Containers::String::suffix(std::size_t begin) const

View except the first size bytes.

MutableStringView Corrade::Containers::String::exceptSuffix(std::size_t size)

View except the last size bytes.

Equivalent to BasicStringView::exceptSuffix(). If size is 0, the result has StringViewFlag::NullTerminated set.

StringView Corrade::Containers::String::exceptSuffix(std::size_t size) const

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

MutableStringView Corrade::Containers::String::except(std::size_t count)

View except the last size bytes.

StringView Corrade::Containers::String::except(std::size_t count) const

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

Array<MutableStringView> Corrade::Containers::String::split(char delimiter)

Split on given character.

Equivalent to BasicStringView::split(char) const.

Array<StringView> Corrade::Containers::String::split(char delimiter) const

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

Array<MutableStringView> Corrade::Containers::String::split(StringView delimiter)

Split on given substring.

Equivalent to BasicStringView::split(StringView) const.

Array<StringView> Corrade::Containers::String::split(StringView delimiter) const

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

Array<MutableStringView> Corrade::Containers::String::splitWithoutEmptyParts(char delimiter)

Split on given character, removing empty parts.

Equivalent to BasicStringView::splitWithoutEmptyParts(char) const.

Array<StringView> Corrade::Containers::String::splitWithoutEmptyParts(char delimiter) const

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

Array<MutableStringView> Corrade::Containers::String::splitOnAnyWithoutEmptyParts(StringView delimiters)

Split on any character from given set, removing empty parts.

Equivalent to BasicStringView::splitOnAnyWithoutEmptyParts(StringView) const.

Array<StringView> Corrade::Containers::String::splitOnAnyWithoutEmptyParts(StringView delimiters) const

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

Array<MutableStringView> Corrade::Containers::String::splitWithoutEmptyParts(StringView delimiters)

Split on any character from given set, removing empty parts.

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

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

Array<MutableStringView> Corrade::Containers::String::splitOnWhitespaceWithoutEmptyParts()

Split on whitespace, removing empty parts.

Equivalent to BasicStringView::splitOnWhitespaceWithoutEmptyParts() const.

Array<StringView> Corrade::Containers::String::splitOnWhitespaceWithoutEmptyParts() const

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

Array<MutableStringView> Corrade::Containers::String::splitWithoutEmptyParts()

Split on whitespace, removing empty parts.

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

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

Array3<MutableStringView> Corrade::Containers::String::partition(char separator)

Partition on a character.

Equivalent to BasicStringView::partition(char) const. The last returned value has always StringViewFlag::NullTerminated set.

Array3<StringView> Corrade::Containers::String::partition(char separator) const

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

Array3<MutableStringView> Corrade::Containers::String::partition(StringView separator)

Partition on a substring.

Equivalent to BasicStringView::partition(StringView) const. The last returned value has always StringViewFlag::NullTerminated set.

Array3<StringView> Corrade::Containers::String::partition(StringView separator) const

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

Array3<MutableStringView> Corrade::Containers::String::partitionLast(char separator)

Partition on a last occurence of a character.

Equivalent to BasicStringView::partition(char) const. The last returned value has always StringViewFlag::NullTerminated set.

Array3<StringView> Corrade::Containers::String::partitionLast(char separator) const

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

Array3<MutableStringView> Corrade::Containers::String::partitionLast(StringView separator)

Partition on a last occurence of a substring.

Equivalent to BasicStringView::partition(StringView) const. The last returned value has always StringViewFlag::NullTerminated set.

Array3<StringView> Corrade::Containers::String::partitionLast(StringView separator) const

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

String Corrade::Containers::String::join(const StringIterable& strings) const

Join strings with this view as the delimiter.

Equivalent to BasicStringView::join().

String Corrade::Containers::String::joinWithoutEmptyParts(const StringIterable& strings) const

Join strings with this view as the delimiter, skipping empty parts.

Equivalent to BasicStringView::joinWithoutEmptyParts().

bool Corrade::Containers::String::hasPrefix(StringView prefix) const

Whether the string begins with given prefix.

Equivalent to BasicStringView::hasPrefix().

bool Corrade::Containers::String::hasPrefix(char prefix) const

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

bool Corrade::Containers::String::hasSuffix(StringView suffix) const

Whether the string ends with given suffix.

Equivalent to BasicStringView::hasSuffix().

bool Corrade::Containers::String::hasSuffix(char suffix) const

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

MutableStringView Corrade::Containers::String::exceptPrefix(StringView prefix)

View with given prefix stripped.

Equivalent to BasicStringView::exceptPrefix().

StringView Corrade::Containers::String::exceptPrefix(StringView prefix) const

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

MutableStringView Corrade::Containers::String::exceptPrefix(char prefix) deleted

Using char literals for prefix stripping is not allowed.

To avoid accidentally interpreting a char literal as a size and calling exceptPrefix(std::size_t) instead, or vice versa, you have to always use a string literal to call this function.

StringView Corrade::Containers::String::exceptPrefix(char prefix) const deleted

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

MutableStringView Corrade::Containers::String::stripPrefix(StringView prefix)

View except the first size bytes.

StringView Corrade::Containers::String::stripPrefix(StringView prefix) const

View except the first size bytes.

MutableStringView Corrade::Containers::String::exceptSuffix(StringView suffix)

View with given suffix stripped.

Equivalent to BasicStringView::exceptSuffix().

StringView Corrade::Containers::String::exceptSuffix(StringView suffix) const

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

MutableStringView Corrade::Containers::String::exceptSuffix(char suffix) deleted

Using char literals for suffix stripping is not allowed.

To avoid accidentally interpreting a char literal as a size and calling exceptSuffix(std::size_t) instead, or vice versa, you have to always use a string literal to call this function.

StringView Corrade::Containers::String::exceptSuffix(char suffix) const deleted

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

MutableStringView Corrade::Containers::String::stripSuffix(StringView suffix)

View except the last size bytes.

StringView Corrade::Containers::String::stripSuffix(StringView suffix) const

View except the last size bytes.

MutableStringView Corrade::Containers::String::trimmed(StringView characters)

View with given characters trimmed from prefix and suffix.

Equivalent to BasicStringView::trimmed(StringView) const.

StringView Corrade::Containers::String::trimmed(StringView characters) const

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

MutableStringView Corrade::Containers::String::trimmed()

View with whitespace trimmed from prefix and suffix.

Equivalent to BasicStringView::trimmed() const.

StringView Corrade::Containers::String::trimmed() const

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

MutableStringView Corrade::Containers::String::trimmedPrefix(StringView characters)

View with given characters trimmed from prefix.

Equivalent to BasicStringView::trimmedPrefix(StringView) const.

StringView Corrade::Containers::String::trimmedPrefix(StringView characters) const

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

MutableStringView Corrade::Containers::String::trimmedPrefix()

View with whitespace trimmed from prefix.

Equivalent to BasicStringView::trimmedPrefix() const.

StringView Corrade::Containers::String::trimmedPrefix() const

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

MutableStringView Corrade::Containers::String::trimmedSuffix(StringView characters)

View with given characters trimmed from suffix.

Equivalent to BasicStringView::trimmedSuffix(StringView) const.

StringView Corrade::Containers::String::trimmedSuffix(StringView characters) const

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

MutableStringView Corrade::Containers::String::trimmedSuffix()

View with whitespace trimmed from suffix.

Equivalent to BasicStringView::trimmedSuffix() const.

StringView Corrade::Containers::String::trimmedSuffix() const

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

MutableStringView Corrade::Containers::String::find(StringView substring)

Find a substring.

Equivalent to BasicStringView::find(StringView) const.

StringView Corrade::Containers::String::find(StringView substring) const

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

MutableStringView Corrade::Containers::String::find(char character)

Find a substring.

Equivalent to BasicStringView::find(char) const, which in turn is a specialization of BasicStringView::find(StringView) const.

StringView Corrade::Containers::String::find(char character) const

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

MutableStringView Corrade::Containers::String::findOr(StringView substring, char* fail)

Find a substring with a custom failure pointer.

Equivalent to BasicStringView::findOr(StringView, T*) const.

StringView Corrade::Containers::String::findOr(StringView substring, const char* fail) const

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

MutableStringView Corrade::Containers::String::findOr(char character, char* fail)

Find a substring with a custom failure pointer.

Equivalent to BasicStringView::findOr(char, T*) const, which in turn is a specialization of BasicStringView::findOr(StringView, T*) const.

StringView Corrade::Containers::String::findOr(char character, const char* fail) const

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

MutableStringView Corrade::Containers::String::findLast(StringView substring)

Find the last occurence of a substring.

Equivalent to BasicStringView::findLast(StringView) const.

StringView Corrade::Containers::String::findLast(StringView substring) const

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

MutableStringView Corrade::Containers::String::findLast(char character)

Find the last occurence of a substring.

Equivalent to BasicStringView::findLast(char) const, which in turn is a specialization of BasicStringView::findLast(StringView) const.

StringView Corrade::Containers::String::findLast(char character) const

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

MutableStringView Corrade::Containers::String::findLastOr(StringView substring, char* fail)

Find the last occurence of a substring with a custom failure pointer.

Equivalent to BasicStringView::findLastOr(StringView, T*) const.

StringView Corrade::Containers::String::findLastOr(StringView substring, const char* fail) const

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

MutableStringView Corrade::Containers::String::findLastOr(char character, char* fail)

Find the last occurence of a substring with a custom failure pointer.

Equivalent to BasicStringView::findLastOr(char, T*) const, which in turn is a specialization of BasicStringView::findLastOr(StringView, T*) const.

StringView Corrade::Containers::String::findLastOr(char character, const char* fail) const

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

bool Corrade::Containers::String::contains(StringView substring) const

Whether the string contains a substring.

Equivalent to BasicStringView::contains(StringView) const.

bool Corrade::Containers::String::contains(char character) const

Whether the string contains a character.

Equivalent to BasicStringView::contains(char) const.

MutableStringView Corrade::Containers::String::findAny(StringView characters)

Find any character from given set.

Equivalent to BasicStringView::findAny().

StringView Corrade::Containers::String::findAny(StringView characters) const

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

MutableStringView Corrade::Containers::String::findAnyOr(StringView characters, char* fail)

Find any character from given set with a custom failure pointer.

Equivalent to BasicStringView::findAnyOr().

StringView Corrade::Containers::String::findAnyOr(StringView characters, const char* fail) const

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

MutableStringView Corrade::Containers::String::findLastAny(StringView characters)

Find the last occurence of any character from given set.

Equivalent to BasicStringView::findLastAny().

StringView Corrade::Containers::String::findLastAny(StringView characters) const

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

MutableStringView Corrade::Containers::String::findLastAnyOr(StringView characters, char* fail)

Find the last occurence of any character from given set with a custom failure pointer.

Equivalent to BasicStringView::findLastAnyOr().

StringView Corrade::Containers::String::findLastAnyOr(StringView characters, const char* fail) const

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

bool Corrade::Containers::String::containsAny(StringView substring) const

Whether the string contains any character from given set.

Equivalent to BasicStringView::containsAny().

char* Corrade::Containers::String::release()

Release data storage.

Returns the data pointer and resets data pointer, size and deleter to be equivalent to a default-constructed instance. Can be called only if the string is not stored using SSO — see Small string optimization for more information. Deleting the returned array is user responsibility — note the string might have a custom deleter() and so delete[] might not be always appropriate. Note also that with custom deleters the returned pointer is not guaranteed to be actually mutable.