#include <Corrade/Containers/StringView.h>
template<class T>
Corrade::Containers::BasicStringView class new in Git master

Base for string views.

A lighter alternative to C++17 std::string_view that has also a mutable variant and additional optimizations for reducing unnecessary copies and allocations. An owning version of this container is a String.

Usage

The class is meant to be used through either the StringView or MutableStringView typedefs. It's implicitly convertible from C string literals, but the recommended way is using the Literals::StringLiterals::operator""_s() literal:

using namespace Containers::Literals;

Containers::StringView a = "hello world!";
Containers::StringView b = "hello world!"_s;

While both expressions are mostly equivalent, the literal is constexpr so you can use it in a compile-time context (and on the other hand, the implicit conversion uses std::strlen() which has some runtime impact). The main difference is however that the literal will annotate the view as global and null-terminated, which can help avoid copies and allocations when lifetime of the data needs to be extended or when dealing with APIs that expect null-terminated strings. Additionally, the literal will also preserve zero bytes inside the string, while implicit conversion from a C string won't:

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

C string literals are implicitly immutable, in order to create a mutable one you need to assign the literal to a char[] (instead of const char*) and then create a MutableStringView in a second step. For example:

char a[] = "hello world!";
Containers::MutableStringView view = a;
view[5] = '\0';

This class is implicitly convertible from and to ArrayView, however note that the conversion will not preserve the global / null-terminated annotations.

String view slicing

The string view class inherits the slicing APIs of ArrayView — slice(), sliceSize(), prefix(), suffix(), exceptPrefix() and exceptSuffix() — and in addition it provides string-specific utilities. These are are all derived from the slicing APIs, which means they also return sub-views of the original string:

Character and substring lookup

Converting StringView 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.

Unlike a String, string views can point to any slice of a larger string and thus can't guarantee null termination. Because of this and because even a view with StringViewFlag::NullTerminated can still contain a '\0' anywhere in the middle, there's no implicit conversion to const char* provided, and the pointer returned by data() should only be used together with size().

The quickest safe way to get a null-terminated string out of a StringView is to convert the view to a String and then use String::data(). However, such operation will unconditionally make a copy of the string, which is unnecessary work if the view was null-terminated already. To avoid that, there's String::nullTerminatedView(), which will make a copy only if the view is not already null-terminated, directly referencing the view with a no-op deleter otherwise. For example, when opening a file using std::fopen():

Containers::StringView file = …;

/* Efficiently ensure fopen() gets a null-terminated C string */
std::FILE* f = std::fopen(Containers::String::nullTerminatedView(file).data(), "rb");
…
std::fclose(f);

Similarly as described in Converting String instances to null-terminated C strings, pointers to data in SSO instances will get invalidated when the instance is moved. With String::nullTerminatedGlobalView(AllocatedInitT, StringView) the null-terminated copy will be always allocated, avoiding this problem:

void exec(int argc, const char* const* argv); /* Takes a C string array */

Containers::Array<Containers::StringView> args;
Containers::Array<Containers::String> data;
Containers::Array<const char*> argv;
for(Containers::StringView arg: args) {
    /* If just arrayAppend(storage, Containers::String::nullTerminatedView(arg))
       was used, the data() passed to argv could be invalidated next time the
       storage gets reallocated */
    arrayAppend(data,
        Containers::String::nullTerminatedView(Containers::AllocatedInit, arg));
    arrayAppend(argv, data.back().data());
}

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

Conversion to array views

String views are implicitly convertible to ArrayView as described in the following table. This also extends to other container types constructibe from ArrayView, which means for example that a StridedArrayView1D is implicitly convertible from a string view as well.

String view type↭Array view type
StringView→ArrayView<const char>
MutableStringView→ArrayView<const char>
MutableStringView→ArrayView<char>

STL compatibility

Instances of StringView and BasicStringView 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
StringView←std::string
StringView←const std::string
StringView→std::string (data copy)
StringView→const std::string (data copy)
MutableStringView←std::string
MutableStringView→std::string (data copy)
MutableStringView→const std::string (data copy)

Example:

#include <Corrade/Containers/StringStl.h>

…

using namespace Containers::Literals;

std::string a = "Hello\0world!"_s;

Containers::MutableStringView b = a;
b[5] = ' ';

Creating a std::string instance always involves a data copy, while going the other way always creates a non-owning reference without allocations or copies. StringView / MutableStringView created from a std::string always have StringViewFlag::NullTerminated set, but the usual conditions regarding views apply — if the original string is modified, view pointer, size or the null termination property may not be valid anymore.

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
StringView⇆std::string_view
MutableStringView→std::string_view

Example:

#include <Corrade/Containers/StringStlView.h>

…

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

The std::string_view type doesn't have any mutable counterpart, so there's no possibility to create a MutableStringView out of it. Because std::string_view doesn't preserve any information about the string origin, neither StringViewFlag::NullTerminated nor StringViewFlag::Global is set in a StringView converted from it.

Finally, the Corrade/Containers/StringStlHash.h header provides a std::hash specialization for StringView / MutableStringView, 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.

Constructors, destructors, conversion operators

BasicStringView(std::nullptr_t = nullptr) constexpr noexcept
Default constructor.
BasicStringView(T* data, std::size_t size, StringViewFlags flags = {}) constexpr noexcept
Construct from a C string of known size.
BasicStringView(String& data) noexcept
Construct from a String.
template<class U = T>
BasicStringView(const String& data) noexcept
Construct from a const String.
BasicStringView(ArrayView<T> data, StringViewFlags flags = {}) noexcept
Construct from an ArrayView.
template<class U>
BasicStringView(BasicStringView<U> mutable_) constexpr noexcept
Construct a StringView from a MutableStringView.
BasicStringView(T* data, StringViewFlags extraFlags = {}) noexcept
Construct from a null-terminated C string.
template<class U, class = decltype(Implementation::StringViewConverter<T, typename std::decay<U && >::type>::from(std::declval<U && >()))>
BasicStringView(U&& other) constexpr noexcept
Construct a view on an external type / from an external representation.
template<class U, class = decltype(Implementation::StringViewConverter<T, U>::to(std::declval<BasicStringView<T>>()))>
operator U() const constexpr
Convert the view to external representation.
operator bool() const explicit constexpr
Whether the string is non-empty and non-null.

Public functions

auto flags() const -> StringViewFlags constexpr
Flags.
auto data() const -> T* constexpr
String data.
auto size() const -> std::size_t constexpr
String size.
auto isEmpty() const -> bool constexpr
Whether the string is empty.
auto begin() const -> T* constexpr
Pointer to the first byte.
auto cbegin() const -> T* constexpr
auto end() const -> T* constexpr
Pointer to (one item after) the last byte.
auto cend() const -> T* constexpr
auto front() const -> T& constexpr
First byte.
auto back() const -> T& constexpr
Last byte.
auto operator[](std::size_t i) const -> T& constexpr
Element access.
auto slice(T* begin, T* end) const -> BasicStringView<T> constexpr
View slice.
auto slice(std::size_t begin, std::size_t end) const -> BasicStringView<T> constexpr
auto sliceSize(T* begin, std::size_t size) const -> BasicStringView<T> constexpr
View slice of given size.
auto sliceSize(std::size_t begin, std::size_t size) const -> BasicStringView<T> constexpr
auto prefix(T* end) const -> BasicStringView<T> constexpr
View prefix until a pointer.
auto suffix(T* begin) const -> BasicStringView<T> constexpr
View suffix after a pointer.
auto prefix(std::size_t size) const -> BasicStringView<T> constexpr
View on the first size bytes.
auto exceptPrefix(std::size_t size) const -> BasicStringView<T> constexpr
View except the first size bytes.
auto suffix(std::size_t begin) const -> BasicStringView<T> deprecated in Git master constexpr
View except the first size bytes.
auto exceptSuffix(std::size_t size) const -> BasicStringView<T> constexpr
View except the last size bytes.
auto except(std::size_t count) const -> BasicStringView<T> deprecated in Git master constexpr
View except the last size bytes.
auto split(char delimiter) const -> Array<BasicStringView<T>>
Split on given character.
auto split(StringView delimiter) const -> Array<BasicStringView<T>>
Split on given substring.
auto splitWithoutEmptyParts(char delimiter) const -> Array<BasicStringView<T>>
Split on given character, removing empty parts.
auto splitOnAnyWithoutEmptyParts(StringView delimiters) const -> Array<BasicStringView<T>>
Split on any character from given set, removing empty parts.
auto splitWithoutEmptyParts(StringView delimiters) const -> Array<BasicStringView<T>> deprecated in Git master
Split on any character from given set, removing empty parts.
auto splitOnWhitespaceWithoutEmptyParts() const -> Array<BasicStringView<T>>
Split on whitespace, removing empty parts.
auto splitWithoutEmptyParts() const -> Array<BasicStringView<T>> deprecated in Git master
Split on whitespace, removing empty parts.
auto partition(char separator) const -> Array3<BasicStringView<T>>
Partition on a character.
auto partition(StringView separator) const -> Array3<BasicStringView<T>>
Partition on a substring.
auto partitionLast(char separator) const -> Array3<BasicStringView<T>>
Partition on a last occurence of a character.
auto partitionLast(StringView separator) const -> Array3<BasicStringView<T>>
Partition on a last occurence of a substring.
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) const -> BasicStringView<T>
View with given prefix stripped.
auto exceptPrefix(char prefix) const -> BasicStringView<T> deleted
Using char literals for prefix stripping is not allowed.
auto stripPrefix(StringView prefix) const -> BasicStringView<T> deprecated in Git master
View except the first size bytes.
auto exceptSuffix(StringView suffix) const -> BasicStringView<T>
View with given suffix stripped.
auto exceptSuffix(char suffix) const -> BasicStringView<T> deleted
Using char literals for suffix stripping is not allowed.
auto stripSuffix(StringView suffix) const -> BasicStringView<T> deprecated in Git master
View except the last size bytes.
auto trimmed(StringView characters) const -> BasicStringView<T>
View with given characters trimmed from prefix and suffix.
auto trimmed() const -> BasicStringView<T>
View with whitespace trimmed from prefix and suffix.
auto trimmedPrefix(StringView characters) const -> BasicStringView<T>
View with given characters trimmed from prefix.
auto trimmedPrefix() const -> BasicStringView<T>
View with whitespace trimmed from prefix.
auto trimmedSuffix(StringView characters) const -> BasicStringView<T>
View with given characters trimmed from suffix.
auto trimmedSuffix() const -> BasicStringView<T>
View with whitespace trimmed from suffix.
auto find(StringView substring) const -> BasicStringView<T>
Find a substring.
auto find(char character) const -> BasicStringView<T>
Find a character.
auto findOr(StringView substring, T* fail) const -> BasicStringView<T>
Find a substring with a custom failure pointer.
auto findOr(char character, T* fail) const -> BasicStringView<T>
Find a character with a custom failure pointer.
auto findLast(StringView substring) const -> BasicStringView<T>
Find the last occurence of a substring.
auto findLast(char character) const -> BasicStringView<T>
Find the last occurence of a character.
auto findLastOr(StringView substring, T* fail) const -> BasicStringView<T>
Find the last occurence a substring with a custom failure pointer.
auto findLastOr(char character, T* fail) const -> BasicStringView<T>
Find the last occurence of a character with a custom failure pointer.
auto contains(StringView substring) const -> bool
Whether the view contains a substring.
auto contains(char character) const -> bool
Whether the view contains a character.
auto findAny(StringView characters) const -> BasicStringView<T>
Find any character from given set.
auto findAnyOr(StringView characters, T* fail) const -> BasicStringView<T>
Find any character from given set with a custom failure pointer.
auto findLastAny(StringView characters) const -> BasicStringView<T>
Find the last occurence of any character from given set.
auto findLastAnyOr(StringView characters, T* fail) const -> BasicStringView<T>
Find the last occurence of any character from given set with a custom failure pointer.
auto containsAny(StringView substring) const -> bool
Whether the view contains any character from given set.
auto count(char character) const -> std::size_t
Count of occurences of given character.

Friends

auto operator==(StringView, StringView) -> bool new in Git master
String view equality comparison.
auto operator!=(StringView, StringView) -> bool new in Git master
String view non-equality comparison.
auto operator<(StringView, StringView) -> bool new in Git master
String view less-than comparison.
auto operator<=(StringView, StringView) -> bool new in Git master
String view less-than-or-equal comparison.
auto operator>=(StringView, StringView) -> bool new in Git master
String view greater-than-or-equal comparison.
auto operator>(StringView, StringView) -> bool new in Git master
String view greater-than comparison.
auto operator+(StringView, StringView) -> String new in Git master
String concatenation.
auto operator*(StringView, std::size_t) -> String new in Git master
String multiplication.

Function documentation

template<class T>
Corrade::Containers::BasicStringView<T>::BasicStringView(std::nullptr_t = nullptr) constexpr noexcept

Default constructor.

A default-constructed instance has StringViewFlag::Global set.

template<class T>
Corrade::Containers::BasicStringView<T>::BasicStringView(T* data, std::size_t size, StringViewFlags flags = {}) constexpr noexcept

Construct from a C string of known size.

Parameters
data C string
size Size of the C string, excluding the null terminator
flags Flags describing additional string properties

If StringViewFlag::Global is set, the data pointer is assumed to never go out of scope, which can avoid copies and allocations in code using the instance. If StringViewFlag::NullTerminated is set, it's expected that data is not nullptr and data[size] == '\0'. That can avoid copies and allocations in code that passes such string to APIs that expect null-terminated strings (such as std::fopen()).

If you're unsure about data origin, the safe bet is to keep flags at their default. On the other hand, C string literals are always global and null-terminated — for those, the recommended way is to use the Literals::StringLiterals::operator""_s() literal instead.

template<class T>
Corrade::Containers::BasicStringView<T>::BasicStringView(String& data) noexcept

Construct from a String.

The resulting view has StringViewFlag::NullTerminated set always, and StringViewFlag::Global if the string was originally created from a global null-terminated view with String::nullTerminatedView() or String::nullTerminatedGlobalView().

template<class T> template<class U = T>
Corrade::Containers::BasicStringView<T>::BasicStringView(const String& data) noexcept

Construct from a const String.

Enabled only if the view is not mutable. The resulting view has StringViewFlag::NullTerminated set always, and StringViewFlag::Global if the string was created from a global null-terminated view with String::nullTerminatedView() or String::nullTerminatedGlobalView().

template<class T>
Corrade::Containers::BasicStringView<T>::BasicStringView(ArrayView<T> data, StringViewFlags flags = {}) noexcept

Construct from an ArrayView.

The resulting view has the same size as data, by default no null-termination is assumed.

template<class T>
Corrade::Containers::BasicStringView<T>::BasicStringView(T* data, StringViewFlags extraFlags = {}) noexcept

Construct from a null-terminated C string.

Contrary to the behavior of std::string, data is allowed to be nullptr — in that case an empty view is constructed.

Calls BasicStringView(T*, std::size_t, StringViewFlags) with size set to std::strlen() of data if data is not nullptr. If data is nullptr, size is set to 0. In addition to extraFlags, if data is not nullptr, StringViewFlag::NullTerminated is set, otherwise StringViewFlag::Global is set.

The BasicStringView(std::nullptr_t) overload (which is a default constructor) is additionally constexpr.

template<class T> template<class U, class = decltype(Implementation::StringViewConverter<T, typename std::decay<U && >::type>::from(std::declval<U && >()))>
Corrade::Containers::BasicStringView<T>::BasicStringView(U&& other) constexpr noexcept

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

template<class T> template<class U, class = decltype(Implementation::StringViewConverter<T, U>::to(std::declval<BasicStringView<T>>()))>
Corrade::Containers::BasicStringView<T>::operator U() const constexpr

Convert the view to external representation.

template<class T>
Corrade::Containers::BasicStringView<T>::operator bool() const explicit constexpr

Whether the string is non-empty and non-null.

Returns true if the string is non-empty and the pointer is not nullptr, false otherwise. If you rely on just one of these conditions, use isEmpty() and data() instead.

template<class T>
T* Corrade::Containers::BasicStringView<T>::data() const constexpr

String data.

The pointer is not guaranteed to be null-terminated, use flags() and StringViewFlag::NullTerminated to check for the presence of a null terminator.

template<class T>
std::size_t Corrade::Containers::BasicStringView<T>::size() const constexpr

String size.

Excludes the null terminator.

template<class T>
bool Corrade::Containers::BasicStringView<T>::isEmpty() const constexpr

Whether the string is empty.

template<class T>
T* Corrade::Containers::BasicStringView<T>::begin() const constexpr

Pointer to the first byte.

template<class T>
T* Corrade::Containers::BasicStringView<T>::cbegin() const constexpr

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

template<class T>
T* Corrade::Containers::BasicStringView<T>::end() const constexpr

Pointer to (one item after) the last byte.

template<class T>
T* Corrade::Containers::BasicStringView<T>::cend() const constexpr

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

template<class T>
T& Corrade::Containers::BasicStringView<T>::front() const constexpr

First byte.

Expects there is at least one byte.

template<class T>
T& Corrade::Containers::BasicStringView<T>::back() const constexpr

Last byte.

Expects there is at least one byte.

template<class T>
T& Corrade::Containers::BasicStringView<T>::operator[](std::size_t i) const constexpr

Element access.

Expects that i is less than size(), or less than or equal to size() if the string is StringViewFlag::NullTerminated.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::slice(T* begin, T* end) const constexpr

View slice.

Both arguments are expected to be in range. Propagates the StringViewFlag::Global flag and if end points to (one item after) the end of the original null-terminated string, the result has StringViewFlag::NullTerminated also.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::slice(std::size_t begin, std::size_t end) const constexpr

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

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::sliceSize(T* begin, std::size_t size) const constexpr

View slice of given size.

Equivalent to data.slice(begin, begin + size).

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::sliceSize(std::size_t begin, std::size_t size) const constexpr

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

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::prefix(T* end) const constexpr

View prefix until a pointer.

Equivalent to string.slice(string.begin(), end). If end is nullptr, returns zero-sized nullptr view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::suffix(T* begin) const constexpr

View suffix after a pointer.

Equivalent to string.slice(begin, string.end()). If begin is nullptr and the original view isn't, returns a zero-sized nullptr view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::prefix(std::size_t size) const constexpr

View on the first size bytes.

Equivalent to string.slice(0, size).

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptPrefix(std::size_t size) const constexpr

View except the first size bytes.

Equivalent to string.slice(size, string.size()).

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::suffix(std::size_t begin) const constexpr

View except the first size bytes.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptSuffix(std::size_t size) const constexpr

View except the last size bytes.

Equivalent to string.slice(0, string.size() - size).

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::except(std::size_t count) const constexpr

View except the last size bytes.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::split(char delimiter) const

Split on given character.

If delimiter is not found, returns a single-item array containing the full input string. If the string is empty, returns an empty array. The function uses slice() internally, meaning it propagates the flags() as appropriate.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::split(StringView delimiter) const

Split on given substring.

If delimiter is not found, returns a single-item array containing the full input string. If the string is empty, returns an empty array. The function uses slice() internally, meaning it propagates the flags() as appropriate.

Note that this function looks for the whole delimiter. If you want to split on any character from a set, use splitOnAnyWithoutEmptyParts() instead.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::splitWithoutEmptyParts(char delimiter) const

Split on given character, removing empty parts.

If delimiter is not found, returns a single-item array containing the full input string. If the string is empty or consists just of delimiter characters, returns an empty array. The function uses slice() internally, meaning it propagates the flags() as appropriate.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::splitOnAnyWithoutEmptyParts(StringView delimiters) const

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

If no characters from delimiters are found, returns a single-item array containing the full input string. If the string is empty or consists just of characters from delimiters, returns an empty array. The function uses slice() internally, meaning it propagates the flags() as appropriate.

If you have just a single delimiter character, split(char) const is more efficient. If you need to split on a multi-character delimiter, use split(StringView) const instead.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::splitWithoutEmptyParts(StringView delimiters) const

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

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::splitOnWhitespaceWithoutEmptyParts() const

Split on whitespace, removing empty parts.

Equivalent to calling splitOnAnyWithoutEmptyParts(StringView) const with " \t\f\v\r\n" passed to delimiters.

template<class T>
Array<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::splitWithoutEmptyParts() const

Split on whitespace, removing empty parts.

template<class T>
Array3<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::partition(char separator) const

Partition on a character.

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.

The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting views are nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
Array3<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::partition(StringView separator) const

Partition on a substring.

Like partition(char) const, but looks for a whole substring instead of a single character.

template<class T>
Array3<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::partitionLast(char separator) const

Partition on a last occurence of a character.

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.

The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting views are nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
Array3<BasicStringView<T>> Corrade::Containers::BasicStringView<T>::partitionLast(StringView separator) const

Partition on a last occurence of a substring.

Like partitionLast(char) const, but looks for a whole substring instead of a single character.

template<class T>
String Corrade::Containers::BasicStringView<T>::join(const StringIterable& strings) const

Join strings with this view as the delimiter.

Similar in usage to Python's str.join() — the following produces "hello, world":

using namespace Containers::Literals;

Containers::String a = ", "_s.join({"hello", "world"});

template<class T>
String Corrade::Containers::BasicStringView<T>::joinWithoutEmptyParts(const StringIterable& strings) const

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

Like join(), but empty items in strings are skipped instead of causing multiple repeated delimiters in the output.

template<class T>
bool Corrade::Containers::BasicStringView<T>::hasPrefix(StringView prefix) const

Whether the string begins with given prefix.

For an empty string returns true only if prefix is empty as well.

template<class T>
bool Corrade::Containers::BasicStringView<T>::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.

template<class T>
bool Corrade::Containers::BasicStringView<T>::hasSuffix(StringView suffix) const

Whether the string ends with given suffix.

For an empty string returns true only if suffix is empty as well.

template<class T>
bool Corrade::Containers::BasicStringView<T>::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.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptPrefix(StringView prefix) const

View with given prefix stripped.

Expects that the string actually begins with given prefix. The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting view is nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptPrefix(char prefix) const 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) const instead, or vice versa, you have to always use a string literal to call this function.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::stripPrefix(StringView prefix) const

View except the first size bytes.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptSuffix(StringView suffix) const

View with given suffix stripped.

Expects that the string actually ends with given suffix. The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting view is nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::exceptSuffix(char suffix) const 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) const instead, or vice versa, you have to always use a string literal to call this function.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::stripSuffix(StringView suffix) const

View except the last size bytes.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmed(StringView characters) const

View with given characters trimmed from prefix and suffix.

The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting view is nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmed() const

View with whitespace trimmed from prefix and suffix.

Equivalent to calling trimmed(StringView) const with " \t\f\v\r\n" passed to characters.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmedPrefix(StringView characters) const

View with given characters trimmed from prefix.

The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting view is nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmedPrefix() const

View with whitespace trimmed from prefix.

Equivalent to calling trimmedPrefix(StringView) const with " \t\f\v\r\n" passed to characters.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmedSuffix(StringView characters) const

View with given characters trimmed from suffix.

The function uses slice() internally, meaning it propagates the flags() as appropriate. Additionally, the resulting view is nullptr only if the input is nullptr, otherwise the view always points to existing memory.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::trimmedSuffix() const

View with whitespace trimmed from suffix.

Equivalent to calling trimmedSuffix(StringView) const with " \t\f\v\r\n" passed to characters.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::find(StringView substring) const

Find a substring.

Returns a view pointing to the first found substring. If not found, an empty nullptr view is returned. The function uses slice() internally, meaning it propagates the flags() as appropriate, except in case of a failure, where it always returns no StringViewFlags.

Note that the function operates with a $ \mathcal{O}(nm) $ complexity and as such is meant mainly for one-time searches in non-performance-critical code. For repeated searches or searches of large substrings it's recommended to use the std::search() algorithms, especially std::boyer_moore_searcher and its variants. Those algorithms on the other hand have to perform certain preprocessing of the input and keep extra state and due to that overhead aren't generally suited for one-time searches. Consider using find(char) const instead for single-byte substrings, see also count(char) const for counting the number of occurences.

This function is equivalent to calling find() on a std::string or a std::string_view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::find(char character) const

Find a character.

Faster than find(StringView) const if the string has just one byte.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findOr(StringView substring, T* fail) const

Find a substring with a custom failure pointer.

Like find(StringView) const, but returns an empty view pointing to the fail value instead of nullptr, which is useful to avoid explicit handling of cases where the substring wasn't found.

The fail value can be nullptr or any other pointer, but commonly it's set to either begin() or end(). For example here when getting the basename and an extension from a file path, similarly to what Utility::Path::split() and splitExtension() does:

Containers::StringView path = …;

/* Filename is everything after the last found slash, or the whole path if
   there's no slash */
Containers::StringView foundSlash = path.findLastOr('/', path.begin());
Containers::StringView filename = path.suffix(foundSlash.end());

/* Extension is the last found dot and everything after, or nothing if there's
   no dot */
Containers::StringView foundDot = filename.findLastOr('.', filename.end());
Containers::StringView extension = filename.suffix(foundDot.begin());

Consider using findOr(char, T*) const for single-byte substrings.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findOr(char character, T* fail) const

Find a character with a custom failure pointer.

Faster than findOr(StringView, T*) const if the string has just one byte.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLast(StringView substring) const

Find the last occurence of a substring.

Returns a view pointing to the last found substring. If not found, an empty nullptr view is returned. The function uses slice() internally, meaning it propagates the flags() as appropriate, except in case of a failure, where it always returns no StringViewFlags.

Similarly as with find(), note that the function operates with a $ \mathcal{O}(nm) $ complexity and as such is meant mainly for one-time searches in non-performance-critical code. See the documentation of find() for further information and suggested alternatives. Consider using findLast(char) const instead for single-byte substrings.

This function is equivalent to calling rfind() on a std::string or a std::string_view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLast(char character) const

Find the last occurence of a character.

Faster than findLast(StringView) const if the string has just one byte.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLastOr(StringView substring, T* fail) const

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

Like findLast(StringView) const, but returns an empty view pointing to the fail value instead of nullptr, which is useful to avoid explicit handling of cases where the substring wasn't found. See findOr() for an example use case.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLastOr(char character, T* fail) const

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

Faster than findLastOr(StringView, T*) const if the string has just one byte.

template<class T>
bool Corrade::Containers::BasicStringView<T>::contains(StringView substring) const

Whether the view contains a substring.

A slightly lighter variant of find() useful when you only want to know if a substring was found or not. Consider using contains(char) const for single-byte substrings, see also count(char) const for counting the number of occurences.

template<class T>
bool Corrade::Containers::BasicStringView<T>::contains(char character) const

Whether the view contains a character.

Faster than contains(StringView) const if the string has just one byte.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findAny(StringView characters) const

Find any character from given set.

Returns a view pointing to the first found character from the set. If no characters from characters are found, an empty nullptr view is returned. The function uses slice() internally, meaning it propagates the flags() as appropriate, except in case of a failure, where it always returns no StringViewFlags.

This function is equivalent to calling find_first_of() on a std::string or a std::string_view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findAnyOr(StringView characters, T* fail) const

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

Like findAny(StringView) const, but returns an empty view pointing to the fail value instead of nullptr, which is useful to avoid explicit handling of cases where no character was found.

The fail value can be nullptr or any other pointer, but commonly it's set to either begin() or end(). For example here when getting everything until the next space character:

Containers::StringView string = …;

/* A word is everything until the next space character, or the whole string if
   there's no space */
Containers::StringView foundSpace = string.findAnyOr(" \n\r\t", string.end());
Containers::StringView word = string.prefix(foundSpace.begin());

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLastAny(StringView characters) const

Find the last occurence of any character from given set.

Returns a view pointing to the last found character from the set. If no characters from characters are found, an empty nullptr view is returned. The function uses slice() internally, meaning it propagates the flags() as appropriate, except in case of a failure, where it always returns no StringViewFlags.

This function is equivalent to calling find_last_of() on a std::string or a std::string_view.

template<class T>
BasicStringView<T> Corrade::Containers::BasicStringView<T>::findLastAnyOr(StringView characters, T* fail) const

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

Like findLastAny(StringView) const, but returns an empty view pointing to the fail value instead of nullptr, which is useful to avoid explicit handling of cases where the substring wasn't found. See findAnyOr() for an example use case.

template<class T>
bool Corrade::Containers::BasicStringView<T>::containsAny(StringView substring) const

Whether the view contains any character from given set.

A slightly lighter variant of findAny() useful when you only want to know if a character was found or not.

template<class T>
std::size_t Corrade::Containers::BasicStringView<T>::count(char character) const

Count of occurences of given character.

If it's only needed to know whether a character is contained in a string at all, consider using contains(char) const instead.

template<class T>
String operator+(StringView, StringView) new in Git master

String concatenation.

For joining more than one string prefer to use StringView::join() to avoid needless temporary allocations.

template<class T>
String operator*(StringView, std::size_t) new in Git master

String multiplication.

Equivalent to string multiplication in Python, returns string repeated count times.

template<class T>
Utility::Debug& operator<<(Utility::Debug& debug, StringViewFlag value)

Debug output operator.

template<class T>
Utility::Debug& operator<<(Utility::Debug& debug, StringViewFlags value)

Debug output operator.

template<class T>
StringView operator""_s(const char* data, std::size_t size) constexpr new in Git master

String view literal.

The returned instance has both StringViewFlag::Global and StringViewFlag::NullTerminated set. See Usage for more information.