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

Wrapper for any sequential container of strings or string views.

Useful where it's desirable to have a single interface accepting an ArrayView of String, StringView or const char* and anything convertible to these.

This class adds extra indirection to allow iterating over various input containers with a single code path. Assuming the API itself isn't bottlenecked on iteration performance, it should be an acceptable tradeoff compared to having to implement multiple code paths or have extra overloads that unify the process by copying the data to a temporary container first.

Usage

A StringIterable can be implicitly created from an ArrayView<StringView> or StridedArrayView1D<StringView>, (strided) array view of (const) String, const char*; std::initializer_list; and any other type convertible to these. Such as plain C arrays, Array or STL types convertible to an ArrayView.

Example usage — passing main() arguments to StringView::join() to print them:

int main(int argc, char** argv);
int main(int argc, char** argv) {
    Utility::Debug{} << " "_s.join(Containers::arrayView(argv, argc)); 
}

Dangling references

Because the type is, like an ArrayView, just a non-owning view on the input data, to avoid dangling references it's recommended to never explicitly instantiate the type. Pass the input data directly instead. The snippet below would compile, however on the last line the API will be accessing an already-destroyed std::initializer_list:

Containers::StringIterable iterable = {"hello", "world"};

Utility::Debug{} << " "_s.join(iterable); // Boom!

On the API implementation side, the usual container interface is exposed — in particular isEmpty(), size(), operator[](), front(), back() as well as range-for access:

void foo(const Containers::StringIterable& strings) {
    for(Containers::StringView string: strings) {
        …
    }
}

STL compatibility

Including Corrade/Containers/StringStl.h will make StringIterable accept sequences of std::string instances as well. When combined with Corrade/Containers/ArrayViewStl.h, it'll accept also a std::vector or std::array of those:

#include <Corrade/Containers/ArrayViewStl.h>
#include <Corrade/Containers/StringStl.h>

…

std::vector<std::string> a{"hello", "world", "!"};
Containers::StringIterable b = a;

On compilers that support C++17, including Corrade/Containers/StringStlView.h will make StringIterable accept also std::string_view instances; when combined with Corrade/Containers/ArrayViewStlSpan.h on compilers supporting C++20 then also std::string and std::string_view instances contained in a std::span:

#include <Corrade/Containers/ArrayViewStlSpan.h>
#include <Corrade/Containers/StringStlView.h>

…

std::span<std::string_view> a = …;
Containers::StringIterable b = a;

Constructors, destructors, conversion operators

StringIterable(std::nullptr_t = nullptr) constexpr noexcept: Default constructor.
template<class U, class = decltype(StringIterable{std::declval<U && >(), Implementation::IterableOverloadPriority<1>{}})> StringIterable(U&& data) noexcept: Construct from any sequential iterable container.
StringIterable(std::initializer_list<StringView> view) noexcept: Construct from an initializer list.
StringIterable(const void* data, const void* context, std::size_t size, std::ptrdiff_t stride, StringView(*)(const void*, const void*, std::ptrdiff_t, std::size_t) accessor) explicit noexcept: Construct a custom iterable.
operator bool() const explicit: Whether the iterable is non-empty.

Public functions

auto data() const -> const void*: Container data pointer.
auto context() const -> const void*: Context pointer.
auto size() const -> std::size_t: Number of items in the container.
auto stride() const -> std::ptrdiff_t: Stride between items in the container.
auto isEmpty() const -> bool: Whether the container is empty.
auto operator[](std::size_t i) const -> StringView: Element access.
auto begin() const -> StringIterableIterator: Iterator to first element.
auto cbegin() const -> StringIterableIterator
auto end() const -> StringIterableIterator: Iterator to (one item after) last element.
auto cend() const -> StringIterableIterator
auto front() const -> StringView: First element.
auto back() const -> StringView: Last element.

Function documentation

Corrade::Containers::StringIterable::StringIterable(std::nullptr_t = nullptr) constexpr noexcept

Default constructor.

Creates an instance with nullptr data and size and stride set to 0.

template<class U, class = decltype(StringIterable{std::declval<U && >(), Implementation::IterableOverloadPriority<1>{}})>
Corrade::Containers::StringIterable::StringIterable(U&& data) noexcept

Construct from any sequential iterable container.

U can be an ArrayView<T>, StridedArrayView1D<T> and any type convertible to these — see ArrayView and StridedArrayView docs for more information.

The T can then be (const) String, StringView, MutableStringView or const char*.

Corrade::Containers::StringIterable::StringIterable(const void* data, const void* context, std::size_t size, std::ptrdiff_t stride, StringView()(const void, const void*, std::ptrdiff_t, std::size_t) accessor) explicit noexcept

Construct a custom iterable.

Parameters
data	Container data pointer
context	Context pointer or `nullptr`
size	Number of items in the container
stride	Stride between items in the container
accessor	Accessor function

For item i, the accessor gets data + i*stride in the first argument, context in the second argument, stride in the third argument and i in the fourth argument. The context is useful for example in case the iterated container contains just offsets to string values stored in an external location. The index can be used for handling various edge cases in the accessor, the stride for example if it's needed to retrieve the previous or next data value as well.

const void* Corrade::Containers::StringIterable::data() const

Container data pointer.

Not meant to be used directly, as the returned value may point to an arbitrary string (view) type, with no possibility to distinguish it.

const void* Corrade::Containers::StringIterable::context() const

Context pointer.

Filled only by StringIterable(const void*, const void*, std::size_t, std::ptrdiff_t, StringView(*)(const void*, const void*)), nullptr otherwise.

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

Number of items in the container.

std::ptrdiff_t Corrade::Containers::StringIterable::stride() const

Stride between items in the container.

Depends on size of the actual string (view) type as well as whether the original container is contiguous.

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

Whether the container is empty.

StringView Corrade::Containers::StringIterable::operator[](std::size_t i) const

Element access.

Expects that i is less than size(). The returned view has StringViewFlag::Global or StringViewFlag::NullTerminated set depending on what the original string instance was — for example, if was a String or a const char*, all items will have StringViewFlag::NullTerminated set.

StringIterableIterator Corrade::Containers::StringIterable::begin() const

Iterator to first element.

StringIterableIterator Corrade::Containers::StringIterable::cbegin() const

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

StringIterableIterator Corrade::Containers::StringIterable::end() const

Iterator to (one item after) last element.

StringIterableIterator Corrade::Containers::StringIterable::cend() const