General Utilities

Supporting Utilities

Introduction

Enum Flags

EnumFlags stores flag bits from a scoped enum in a small value object. Use it when a public API needs a set of independent flags but should not accept arbitrary integers by accident.

Define flag enums as enum class values with an unsigned underlying type. When you want to use the complement operator, add an All entry that contains every valid bit. The complement is then bounded to All instead of the whole underlying integer type.

Basic Usage

Prefer defining a small alias and an explicit free operator| next to the enum:

enum class Mode : uint8_t {
    Read = 1U << 0U,
    Write = 1U << 1U,
    Execute = 1U << 2U,
    All = (1U << 0U) | (1U << 1U) | (1U << 2U),
};

using Modes = el::EnumFlags<Mode>;

[[nodiscard]] constexpr auto operator|(Mode left, Mode right) noexcept -> Modes {
    return Modes{left} | right;
}

auto modes = Mode::Read | Mode::Write;
modes.set(Mode::Execute);

Raw Values

Use toRawValue() and fromRawValue() at boundaries where raw bits are required. Raw construction preserves all bits, including bits outside All. This makes raw import explicit and avoids silently changing data from an external source.

Named Flag Wrappers

When a flag set needs domain-specific methods, define a named class using the optional CRTP parameter. Inherit the Core constructors so the wrapper retains the regular single-flag and initializer-list syntax:

class Modes : public el::EnumFlags<Mode, Modes> {
    using Base = el::EnumFlags<Mode, Modes>;

public:
    using Base::Base;

    auto toString() const -> el::String;
};

The derived class must be nothrow default-constructible. Bitwise operators, compound assignments and fromRawValue() return the derived type, so domain-specific methods remain available on expression results.

Hash Helper

The hash helpers implement the small combining pattern used by Erbsland Core value types. combineHash() merges two already-computed hash values. advanceHash() hashes one argument with std::hash and combines it with the current hash value.

createHash() starts with 0 and sequentially advances the hash for all provided arguments. Use it when a type’s hash depends on more than one stored value.

Only combineHash() is a compile-time helper. advanceHash() and createHash() call std::hash, whose call operator is not required to be constexpr in C++20.

CoGenerator

CoGenerator is a small C++20 coroutine generator for lazily yielding a sequence of values. It is intended for internal algorithms and compact public helpers where a full container would add unnecessary storage or control-flow noise.

Generators are move-only and single-pass. Consume one generator either with next() or with range iteration, but do not mix both styles for the same instance. Exceptions that escape from the coroutine body are rethrown when the consumer advances the generator.

Use next() when yielded values must be moved out of the coroutine frame, for example for move-only values. Range iteration exposes yielded values as const references while the iterator is positioned at the value.

CoTask

CoTask represents one eagerly started coroutine result. It is move-only and has one consumer. Poll isComplete() when integrating with non-coroutine code, inspect a completed value through result(), move it out through takeResult(), or await and consume the task as an rvalue.

CoTask::run() moves bounded work onto the process-wide coroutine worker service. This service is separate from stream native-I/O workers, and continuations resume without caller-thread affinity. Exceptions are stored and rethrown by result retrieval or co_await. Destroying an incomplete task requests cancellation; an already running callable finishes normally, but a cancelled Erbsland Core coroutine does not continue past its next awaited completion.

CoAsyncGenerator

CoAsyncGenerator is the asynchronous counterpart to CoGenerator. Its producer starts lazily and may combine co_yield with co_await. Each co_await generator.next() produces an optional value, with an empty optional marking completion.

The generator is move-only and single-pass, and only one next() may be outstanding. Exceptions from its producer are rethrown by next(). Use this type for parser, tokenizer, or stream sequences whose producer must suspend between values; keep CoGenerator for simple synchronous pull sequences.

Results With Data

ResultWithData combines the success/failure state of Result with a typed payload. Its optional second template argument selects the Result -derived status base, preserving the specialized states and predicates while exposing data through data() and takeData().

Convenience Collections

Shared Empty Storage

Default-constructed collections reuse one empty raw container for each eligible raw container type. The first operation that requests mutable access detaches and creates private storage, leaving other empty collections unchanged.

Lists always use shared empty storage. Sets and maps use it when their comparison policy is stateless; hash sets and hash maps use it when both their hash and equality policies are stateless. A policy is considered stateless when std::is_empty_v is true. Collections with stateful policies keep independently constructed empty storage so each policy instance retains its own state.

Interface

template<typename tValue> class CoAsyncGenerator

An asynchronous, single-pass coroutine generator.

Unlike CoGenerator, advancing this generator is itself asynchronous. The producer may use both co_yield and co_await; consumers request values with co_await generator.next(). The generator is move-only and permits one outstanding next() operation.

Template Parameters:

tValue – The yielded value type.

Public Types

using Value = tValue : The yielded value type.

using handle_type = std::coroutine_handle<promise_type>: The producer coroutine handle type.

Public Functions

CoAsyncGenerator() = default: Create an empty generator.

inline explicit CoAsyncGenerator(handle_type handle) noexcept

Create a generator from its coroutine handle.

Parameters:: handle – The producer coroutine handle.

inline ~CoAsyncGenerator(): Destroy the producer coroutine.

inline CoAsyncGenerator(CoAsyncGenerator &&other) noexcept

Move ownership from another generator.

Parameters:: other – The generator whose coroutine is transferred.

inline CoAsyncGenerator &operator=(CoAsyncGenerator &&other) noexcept: Replace this generator’s coroutine with another generator’s coroutine.

inline NextOperation next() noexcept

Request the next generated value.

Returns:: An awaitable operation that produces the next value, or an empty optional at completion. Awaiting the returned operation rethrows exceptions that escaped from the producer coroutine.

template<typename tValue> class CoGenerator

A C++20 coroutine generator for yielding a single-pass sequence of values.

CoGenerator owns the coroutine state and destroys it when the generator object is destroyed. Values can be consumed either with next() or through range iteration. Do not mix both consumption styles for the same generator. The generator is move-only, and iterators remain valid only while the owning generator object is alive.

Template Parameters:

tValue – The value type yielded by the coroutine.

Public Types

using Value = tValue : The value type yielded by this generator.

using handle_type = std::coroutine_handle<promise_type>: The standard coroutine handle type.

using iterator = Iterator: The standard iterator type.

Public Functions

CoGenerator() = default: Create an empty generator.

inline explicit CoGenerator(handle_type handle) noexcept

Create a generator from a coroutine handle.

Parameters:: handle – The coroutine handle this generator takes ownership of.

inline ~CoGenerator(): Destroy the owned coroutine state, if present.

inline CoGenerator(CoGenerator &&other) noexcept

Move a generator, transferring ownership of the coroutine state.

Parameters:: other – The generator to move from.

inline CoGenerator &operator=(CoGenerator &&other) noexcept

Move-assign a generator, replacing any owned coroutine state.

Parameters:: other – The generator to move from.
Returns:: A reference to this generator.

inline std::optional<Value> next()

Consume the next yielded value.

Throws:: Any – exception that escaped from the coroutine body.
Returns:: The next value, or an empty optional if the coroutine has finished.

inline iterator begin()

Create an iterator at the first yielded value.

Throws:: Any – exception that escaped from the coroutine body.
Returns:: An iterator for the first value, or end() if the coroutine has finished.

inline iterator end() noexcept

Create the end iterator.

Returns:: The end iterator.

template<typename tValue> class CoTask

An eagerly started, single-consumer coroutine task.

CoTask stores its result independently from the coroutine frame. Destroying an incomplete task requests cancellation; Erbsland Core coroutine awaiters observe that request at their next completion and unwind the coroutine. Continuations run on the thread that completes the awaited operation and have no caller-thread affinity.

Template Parameters:

tValue – The task result type.

Public Types

using promise_type = impl::CoTaskPromise<tValue>

Coroutine promise that owns the shared state of a task with a result.

Public Functions

CoTask() = default: Create an empty task.

inline CoTask(CoTask &&other) noexcept

Move ownership from another task.

Parameters:: other – The task whose state is transferred.

inline ~CoTask(): Request cancellation when this task is still incomplete.

inline CoTask &operator=(CoTask &&other) noexcept: Move task ownership from another task.

inline bool isComplete() const noexcept

Test if this task completed.

Returns:: true if the task is empty or its coroutine completed.

inline const tValue &result() const

Access the completed result.

Throws:

err::LogicError – If the task is empty, incomplete, or its result was consumed.
Any – exception produced by the coroutine.

Returns:

A reference to the stored result without consuming it.

inline tValue takeResult()

Take the completed result.

Throws:

err::LogicError – If the task is empty, incomplete, or its result was consumed.
Any – exception produced by the coroutine.

Returns:

The moved task result.

inline void cancel() noexcept

Request cancellation of this task.

Running bounded work is allowed to finish; the coroutine unwinds instead of resuming user code afterward.

inline impl::CoTaskAwaiter<tValue> operator co_await() &&

Await and consume this task result.

Throws:: err::LogicError – If this task is empty.
Returns:: An awaiter for the result.

Public Static Functions

template<typename tFunction> static inline CoTask run(tFunction function)

Run a callable on the coroutine worker service.

Template Parameters:: tFunction – The callable type.
Parameters:: function – The callable to execute.
Returns:: An eagerly started task for the callable result. Exceptions from the callable are stored in the task and rethrown when its result is observed.

template<impl::EnumFlagsEnum tEnum, typename tDerived = void> class EnumFlags

A safe value wrapper for scoped enum flags.

See: General Utilities

Template Parameters:

tEnum – The scoped enum type with unsigned underlying type.
tDerived – Optional CRTP-derived result type. It must be nothrow default-constructible.

Public Types

using Enum = tEnum : The enum type used for the individual flags.

using Value = typename impl::EnumFlagsTraits<tEnum>::Value: The unsigned integer type used to store the raw flag bits.

Public Functions

constexpr EnumFlags() noexcept = default: Create an empty flag set.

inline constexpr EnumFlags(tEnum flag) noexcept

Create a flag set with one enum flag.

Parameters:: flag – The flag to set.

inline constexpr EnumFlags(std::initializer_list<tEnum> flags) noexcept

Create a flag set from a list of enum flags.

Parameters:: flags – The flags to set.

constexpr bool operator==(const EnumFlags &other) const noexcept = default: Test if two flag sets store the same raw bits.

inline constexpr Result operator&(EnumFlags other) const noexcept

Calculate the intersection of this flag set and another flag set.

Parameters:: other – The other flag set.
Returns:: The flags common to both sets.

inline constexpr Result operator&(tEnum flag) const noexcept

Calculate the intersection of this flag set and an enum flag.

Parameters:: flag – The flag to intersect with.
Returns:: The flags common to both sets.

inline constexpr Result &operator&=(EnumFlags other) noexcept

Keep only the bits also set in another flag set.

Parameters:: other – The flag set to intersect with.
Returns:: A reference to this flag set.

inline constexpr Result &operator&=(tEnum flag) noexcept

Keep only the bits also set in an enum flag.

Parameters:: flag – The flag to intersect with.
Returns:: A reference to this flag set.

inline constexpr Result operator|(EnumFlags other) const noexcept

Calculate the union of this flag set and another flag set.

Parameters:: other – The other flag set.
Returns:: The combined flags.

inline constexpr Result operator|(tEnum flag) const noexcept

Calculate the union of this flag set and an enum flag.

Parameters:: flag – The flag to add.
Returns:: The combined flags.

inline constexpr Result &operator|=(EnumFlags other) noexcept

Add all bits from another flag set.

Parameters:: other – The flag set to add.
Returns:: A reference to this flag set.

inline constexpr Result &operator|=(tEnum flag) noexcept

Add all bits from an enum flag.

Parameters:: flag – The flag to add.
Returns:: A reference to this flag set.

inline constexpr Result operator^(EnumFlags other) const noexcept

Calculate the exclusive union of this flag set and another flag set.

Parameters:: other – The other flag set.
Returns:: The flags set in exactly one of the two sets.

inline constexpr Result operator^(tEnum flag) const noexcept

Calculate the exclusive union of this flag set and an enum flag.

Parameters:: flag – The flag to toggle.
Returns:: The toggled flags.

inline constexpr Result &operator^=(EnumFlags other) noexcept

Toggle all bits from another flag set.

Parameters:: other – The flag set to toggle.
Returns:: A reference to this flag set.

inline constexpr Result &operator^=(tEnum flag) noexcept

Toggle all bits from an enum flag.

Parameters:: flag – The flag to toggle.
Returns:: A reference to this flag set.

inline constexpr auto operator~() const noexcept -> Result 

Calculate the bounded complement of this flag set using tEnum::All as the valid bit domain.

Returns:: The inverted flags within the valid domain.

inline constexpr bool isEmpty() const noexcept

Test if this flag set is empty.

Returns:: true if no flags are set.

inline constexpr bool hasAny() const noexcept

Test if this flag set contains at least one raw bit.

Returns:: true if any flag is set.

inline constexpr bool isSet(tEnum flag) const noexcept

Test if all bits of an enum flag are set.

Parameters:: flag – The flag to check.
Returns:: true if the flag is set.

inline constexpr bool isCleared(tEnum flag) const noexcept

Test if all bits of an enum flag are cleared.

Parameters:: flag – The flag to check.
Returns:: true if the flag is cleared.

inline constexpr bool contains(EnumFlags flags) const noexcept

Test if all bits from another flag set are set.

Parameters:: flags – The flags to check.
Returns:: true if all specified flags are set.

inline constexpr bool intersects(EnumFlags flags) const noexcept

Test if at least one bit from another flag set is set.

Parameters:: flags – The flags to check.
Returns:: true if any of the specified flags are set.

inline constexpr void set(tEnum flag) noexcept

Set all bits from an enum flag.

Parameters:: flag – The flag to set.

inline constexpr void set(EnumFlags flags) noexcept

Set all bits from another flag set.

Parameters:: flags – The flags to set.

inline constexpr void clear(tEnum flag) noexcept

Clear all bits from an enum flag.

Parameters:: flag – The flag to clear.

inline constexpr void clear(EnumFlags flags) noexcept

Clear all bits from another flag set.

Parameters:: flags – The flags to clear.

inline constexpr void clear() noexcept: Clear all bits.

inline constexpr void replaceMasked(EnumFlags flags, EnumFlags mask) noexcept

Replace only the bits selected by mask with the corresponding bits from flags.

Parameters:

flags – The new flag bits.
mask – The mask selecting which bits to replace.

inline constexpr Value toRawValue() const noexcept

Return the raw flag bits.

Returns:: The underlying integer value.

Public Static Functions

static inline constexpr Result fromRawValue(Value value) noexcept

Create a flag set from raw flag bits.

Parameters:: value – The raw flag bits.
Returns:: A new flag set with the given bits.

Friends

inline friend constexpr Result operator&(tEnum flag, EnumFlags flags) noexcept: Calculate the intersection of an enum flag and a flag set.

inline friend constexpr Result operator|(tEnum flag, EnumFlags flags) noexcept: Calculate the union of an enum flag and a flag set.

inline friend constexpr Result operator^(tEnum flag, EnumFlags flags) noexcept: Calculate the exclusive union of an enum flag and a flag set.

constexpr std::size_t erbsland::util::combineHash(const std::size_t hash1, const std::size_t hash2) noexcept

Combines two hash values into a single hash value.

This function uses a common hash combination algorithm (often attributed to Boost) to combine two std::size_t hash values into one.

Parameters:

hash1 – The first hash value.
hash2 – The second hash value.

Returns:

The combined hash value.

template<typename T> void erbsland::util::advanceHash(std::size_t &hash, const T &arg) noexcept

Advances an existing hash value by hashing a new argument and combining it.

This function hashes the provided argument using std::hash and then combines it with the current hash value using combineHash.

Template Parameters:

T – The type of the argument to hash.

Parameters:

hash – The current hash value, which will be updated.
arg – The argument to be hashed and combined.

template<typename T1, typename ...Rest> std::size_t erbsland::util::createHash(const T1 &arg1, const Rest&... rest) noexcept

Creates a new hash value from one or more arguments.

Combines hashes of all arguments into a single value.

See: General Utilities

Template Parameters:

T1 – The type of the first argument.
Rest – The types of the remaining arguments.

Parameters:

arg1 – The first argument.
rest – The remaining arguments.

Returns:

The combined hash value of all arguments.

template<typename tKey, typename tValue, typename tHash = std::hash<tKey>, typename tEqual = std::equal_to<tKey>, typename tSelf = void> class HashMap

A copy-on-write unordered key/value container with Erbsland-style access and algorithms.

See: General Utilities

Template Parameters:

tKey – The key type.
tValue – The value type.
tHash – The key hash type.
tEqual – The key equality type.
tSelf – Internal CRTP type used by derived public hash map types.

Subclassed by erbsland::text::impl::StringHashMap< std::size_t >, erbsland::text::impl::StringHashMap< TlsConfigurationConstPtr >, erbsland::text::impl::StringHashMap< erbsland::event::EventId >, erbsland::text::impl::StringHashMap< erbsland::event::EventBackendId >, erbsland::text::impl::StringHashMap< erbsland::text::U8String >, erbsland::text::impl::StringHashMap< std::shared_ptr< const erbsland::text::U8Format > >, erbsland::text::impl::StringHashMap< erbsland::re::impl::LabelTargetWithSource >, erbsland::text::impl::StringHashMap< CaptureGroupIndex >, erbsland::text::impl::StringHashMap< erbsland::text::impl::StringHashMap >, erbsland::text::impl::StringHashMap< erbsland::system::UserName >, erbsland::text::impl::StringHashMap< erbsland::system::GroupName >, erbsland::text::impl::StringHashMap< erbsland::system::UserId >, erbsland::text::impl::StringHashMap< erbsland::system::GroupId >

Public Types

using Key = tKey : The key type.

using Value = tValue : The value type.

using Entry = std::pair<Key, Value>: One map entry.

using Hash = tHash : The key hash type.

using Equal = tEqual : The key equality type.

using Raw = std::unordered_map<Key, Value, Hash, Equal>: The wrapped standard container.

using Storage = mem::CowManualStorage<Raw>: The COW storage type.

using Count = unit::ItemCount : The element count type.

using Self = std::conditional_t<std::is_void_v<tSelf>, HashMap<Key, Value, Hash, Equal>, tSelf>: The fluent return type.

using key_type = Key : Standard container key type.

using mapped_type = Value : Standard mapped value type.

using value_type = Entry : Standard container value type.

using const_iterator = Raw::const_iterator: Standard const iterator type.

Public Functions

HashMap(): Create an empty hash map.

explicit HashMap(std::initializer_list<Entry> values)

Create a hash map from an initializer list.

Parameters:: values – The key-value pairs to insert.

explicit HashMap(const Raw &raw)

Create a hash map from a standard unordered map.

Parameters:: raw – The map to copy.

explicit HashMap(Raw &&raw)

Create a hash map from a standard unordered map, taking ownership.

Parameters:: raw – The map to move.

const Raw &toRawValue() const noexcept

Return a reference to the underlying standard unordered map.

Returns:: The wrapped map.

std::map<Key, Value> toStdMap() const

Convert to a standard ordered map.

Returns:: An ordered map with all entries.

Raw toStdUnorderedMap() const

Convert to a standard unordered map.

Returns:: A copy of the wrapped map.

std::vector<Key> toStdKeyVector() const

Convert keys to a standard vector.

Returns:: A vector with all keys.

std::vector<Entry> toStdVector() const

Convert entries to a standard vector.

Returns:: A vector with all entries.

Set<Key> toKeySet() const

Convert keys to an ordered set.

Returns:: A set with all keys.

HashSet<Key, Hash, Equal> toKeyHashSet() const

Convert keys to a hash set.

Returns:: A hash set with all keys.

Set<Value> toValueSet() const

Convert values to an ordered set.

Returns:: A set with all values.

HashSet<Value> toValueHashSet() const

Convert values to a hash set.

Returns:: A hash set with all values.

Count count() const noexcept

Return the number of entries.

Returns:: The entry count.

template<typename Function> Count countIf(Function function) const

Count all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: The number of matching entries.

template<typename Function> Count countIfKey(Function function) const

Count all keys matching a predicate.

Parameters:: function – The predicate called with each key.
Returns:: The number of matching keys.

template<typename Function> Count countIfValue(Function function) const

Count all values matching a predicate.

Parameters:: function – The predicate called with each value.
Returns:: The number of matching values.

std::optional<Value> get(const Key &key) const

Get a value by key.

Parameters:: key – The key to look up.
Returns:: The value, or std::nullopt if not found.

Value get(const Key &key, const Value &defaultValue) const

Get a value by key, with a default.

Parameters:

key – The key to look up.
defaultValue – The value to return if not found.

Returns:

The value, or the default.

Entry first() const

Get an arbitrary entry.

Returns:: A copy of an entry.

Entry last() const

Get an arbitrary entry.

Returns:: A copy of an entry.

List<Key> toKeyList() const

Convert keys to a list.

Returns:: A list with all keys.

List<Value> toValueList() const

Convert values to a list.

Returns:: A list with all values.

List<Entry> toList() const

Convert entries to a list.

Returns:: A list with all entries.

Self &reserve(Count count)

Reserve capacity.

Parameters:: count – The minimum capacity to reserve.
Returns:: A reference to this map.

Count capacity() const noexcept

Return the current capacity.

Returns:: The current capacity.

Self &shrinkToFit()

Shrink the underlying storage to fit.

Returns:: A reference to this map.

Self &clear()

Remove all entries.

Returns:: A reference to this map.

Self &swap(Self &other) noexcept

Swap with another map.

Parameters:: other – The map to swap with.
Returns:: A reference to this map.

Self &remove(const Key &key)

Remove an entry by key.

Parameters:: key – The key to remove.
Returns:: A reference to this map.

template<typename Function> Self &removeIf(Function function)

Remove all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A reference to this map.

template<typename Function> Self &removeIfKey(Function function)

Remove all entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A reference to this map.

template<typename Function> Self &removeIfValue(Function function)

Remove all entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A reference to this map.

Self removed(const Key &key) const

Return a hash map without one key.

Parameters:: key – The key to remove.
Returns:: A new hash map without the key.

template<typename Function> Self removedIf(Function function) const

Return a hash map without entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A new hash map without matching entries.

template<typename Function> Self removedIfKey(Function function) const

Return a hash map without entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A new hash map without matching keys.

template<typename Function> Self removedIfValue(Function function) const

Return a hash map without entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A new hash map without matching values.

Value take(const Key &key)

Take a value by key.

Parameters:: key – The key to take.
Returns:: The value associated with the key.

template<typename Function> Self takeIf(Function function)

Take all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A hash map containing the taken entries.

template<typename Function> Self takeIfKey(Function function)

Take all entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A hash map containing the taken entries.

template<typename Function> Self takeIfValue(Function function)

Take all entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A hash map containing the taken entries.

template<typename Function> LoopResult forEach(Function function) const

Call a function for every entry.

Parameters:: function – The function called with each entry.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachKey(Function function) const

Call a function for every key.

Parameters:: function – The function called with each key.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachValue(Function function) const

Call a function for every value.

Parameters:: function – The function called with each value.
Returns:: The result of the iteration.

template<typename Function> Self &mapValue(Function function)

Replace every value with the result of a function.

Parameters:: function – The function used to map values.
Returns:: A reference to this map.

template<typename Function> Self mappedValues(Function function) const

Return a copy with every value mapped through a function.

Parameters:: function – The function used to map values.
Returns:: A mapped copy of the map.

template<typename tValueFwd> Self &set(const Key &key, tValueFwd &&value)

Set a key-value pair.

Parameters:

key – The key.
value – The value.

Returns:

A reference to this map.

template<typename tValueFwd> Self &set(Key &&key, tValueFwd &&value)

Set a key-value pair, taking ownership of the key.

Parameters:

key – The key.
value – The value.

Returns:

A reference to this map.

template<typename tValueFwd> bool tryReplace(const Key &key, tValueFwd &&value)

Try to replace an existing value.

Parameters:

key – The key to replace.
value – The new value.

Returns:

true if the key existed and was replaced.

template<typename tValueFwd> bool tryReplace(Key &&key, tValueFwd &&value)

Try to replace an existing value, taking ownership of the key when replaced.

Parameters:

key – The key to replace.
value – The new value.

Returns:

true if the key existed and was replaced.

template<typename tValueFwd> bool tryInsert(const Key &key, tValueFwd &&value)

Try to insert a new entry.

Parameters:

key – The key.
value – The value.

Returns:

true if the key was not already present.

template<typename tValueFwd> bool tryInsert(Key &&key, tValueFwd &&value)

Try to insert a new entry, taking ownership of the key when inserted.

Parameters:

key – The key.
value – The value.

Returns:

true if the key was not already present.

bool compare(const Self &other) const

Test if two maps contain the same entries.

Parameters:: other – The map to compare with.
Returns:: true if both maps have the same key-value pairs.

bool compareKeys(const Self &other) const

Test if two maps contain the same keys.

Parameters:: other – The map to compare with.
Returns:: true if both maps have the same keys.

bool contains(const Key &key) const

Test if the map contains a key.

Parameters:: key – The key to search for.
Returns:: true if the key is present.

template<typename Function> bool allOf(Function function) const

Test if all entries match a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if all entries match.

template<typename Function> bool anyOf(Function function) const

Test if any entry matches a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if at least one entry matches.

template<typename Function> bool noneOf(Function function) const

Test if no entry matches a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if no entry matches.

const_iterator begin() const noexcept

Return an iterator to the first entry.

Returns:: The begin iterator.

const_iterator end() const noexcept

Return an iterator past the last entry.

Returns:: The end iterator.

Friends

inline friend void swap(HashMap &first, HashMap &second) noexcept

Swap two hash maps.

Parameters:

first – The first hash map.
second – The second hash map.

template<typename tKey, typename tHash, typename tEqual, typename tSelf> class HashSet

A copy-on-write unordered key container with Erbsland-style access and set algorithms.

See: General Utilities

Template Parameters:

tKey – The key type.
tHash – The key hash type.
tEqual – The key equality type.
tSelf – Internal CRTP type used by derived public hash set types.

Public Types

using Key = tKey : The key type.

using Hash = tHash : The key hash type.

using Equal = tEqual : The key equality type.

using Raw = std::unordered_set<Key, Hash, Equal>: The wrapped standard container.

using Storage = mem::CowManualStorage<Raw>: The COW storage type.

using Count = unit::ItemCount : The element count type.

using Self = std::conditional_t<std::is_void_v<tSelf>, HashSet<Key, Hash, Equal>, tSelf>: The fluent return type.

using key_type = Key : Standard container key type.

using value_type = Key : Standard container value type.

using const_iterator = typename Raw::const_iterator: Standard const iterator type.

Public Functions

HashSet(): Create an empty hash set.

explicit HashSet(std::initializer_list<Key> values)

Create a hash set from an initializer list.

Parameters:: values – The keys to insert.

explicit HashSet(const Raw &raw)

Create a hash set from a standard unordered set.

Parameters:: raw – The set to copy.

explicit HashSet(Raw &&raw)

Create a hash set from a standard unordered set, taking ownership.

Parameters:: raw – The set to move.

const Raw &toRawValue() const noexcept

Return a reference to the underlying standard unordered set.

Returns:: The wrapped set.

List<Key> toList() const

Convert to a list.

Returns:: A list with all keys.

std::vector<Key> toStdVector() const

Convert to a standard vector.

Returns:: A vector with all keys.

std::set<Key> toStdSet() const

Convert to a standard set.

Returns:: An ordered set with all keys.

Raw toStdUnorderedSet() const

Convert to a standard unordered set.

Returns:: A copy of the wrapped set.

Count count() const noexcept

Return the number of elements.

Returns:: The element count.

template<typename Function> Count countIf(Function function) const

Count all keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: The number of matching keys.

Key first() const

Get an arbitrary element.

Returns:: A copy of an element.

Key last() const

Get an arbitrary element.

Returns:: A copy of an element.

Self &reserve(Count count)

Reserve capacity.

Parameters:: count – The minimum capacity to reserve.
Returns:: A reference to this set.

Count capacity() const noexcept

Return the current capacity.

Returns:: The current capacity.

Self &shrinkToFit()

Shrink the underlying storage to fit.

Returns:: A reference to this set.

Self &clear()

Remove all elements.

Returns:: A reference to this set.

Self &swap(Self &other) noexcept

Swap with another set.

Parameters:: other – The set to swap with.
Returns:: A reference to this set.

Self &remove(const Key &key)

Remove a key.

Parameters:: key – The key to remove.
Returns:: A reference to this set.

bool tryRemove(const Key &key)

Try to remove a key.

Parameters:: key – The key to remove.
Returns:: true if the key was present and removed.

template<typename Function> Self &removeIf(Function function)

Remove all keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: A reference to this set.

Self removed(const Key &key) const

Return a set with a key removed.

Parameters:: key – The key to remove.
Returns:: A new set without the key.

template<typename Function> Self removedIf(Function function) const

Return a set without keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: A new set without matching keys.

template<typename Function> LoopResult forEach(Function function) const

Call a function for every key.

Parameters:: function – The function called for every key.
Returns:: The result of the iteration.

Self &unite(const Self &other)

Unite with another set (union).

Parameters:: other – The set to unite with.
Returns:: A reference to this set.

Self &intersect(const Self &other)

Intersect with another set.

Parameters:: other – The set to intersect with.
Returns:: A reference to this set.

Self &subtract(const Self &other)

Subtract another set (difference).

Parameters:: other – The set to subtract.
Returns:: A reference to this set.

Self &symmetricDifference(const Self &other)

Compute the symmetric difference with another set.

Parameters:: other – The set for the symmetric difference.
Returns:: A reference to this set.

Self unitedWith(const Self &other) const

Return the union of this set and another.

Parameters:: other – The set to unite with.
Returns:: A new set containing all elements.

Self intersectedWith(const Self &other) const

Return the intersection of this set and another.

Parameters:: other – The set to intersect with.
Returns:: A new set containing common elements.

Self subtractedBy(const Self &other) const

Return the difference of this set from another.

Parameters:: other – The set to subtract.
Returns:: A new set with elements of other removed.

Self symmetricDifferenceWith(const Self &other) const

Return the symmetric difference with another set.

Parameters:: other – The set for the symmetric difference.
Returns:: A new set with elements unique to either set.

Self &insert(const Key &key)

Insert a key.

Parameters:: key – The key to insert.
Returns:: A reference to this set.

Self &insert(Key &&key)

Insert a key, taking ownership of the value.

Parameters:: key – The key to insert.
Returns:: A reference to this set.

bool tryInsert(const Key &key)

Try to insert a key.

Parameters:: key – The key to insert.
Returns:: true if the key was not already present.

bool tryInsert(Key &&key)

Try to insert a key, taking ownership of the value.

Parameters:: key – The key to insert.
Returns:: true if the key was not already present.

bool compare(const Self &other) const

Test if two sets contain the same elements.

Parameters:: other – The set to compare with.
Returns:: true if both sets contain the same keys.

bool contains(const Key &key) const

Test if the set contains a key.

Parameters:: key – The key to search for.
Returns:: true if the key is present.

template<typename Function> bool allOf(Function function) const

Test if all keys match a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if all keys match.

template<typename Function> bool anyOf(Function function) const

Test if any key matches a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if at least one key matches.

template<typename Function> bool noneOf(Function function) const

Test if no key matches a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if no key matches.

bool isSubsetOf(const Self &other) const

Test if this set is a subset of another.

Parameters:: other – The superset to compare with.
Returns:: true if all elements are in other.

bool isSupersetOf(const Self &other) const

Test if this set is a superset of another.

Parameters:: other – The subset to compare with.
Returns:: true if all elements of other are in this set.

bool isDisjointWith(const Self &other) const

Test if this set has no elements in common with another.

Parameters:: other – The set to compare with.
Returns:: true if the sets share no elements.

bool intersects(const Self &other) const

Test if this set shares any elements with another.

Parameters:: other – The set to compare with.
Returns:: true if there is at least one common element.

const_iterator begin() const noexcept

Return an iterator to the first key.

Returns:: The begin iterator.

const_iterator end() const noexcept

Return an iterator past the last key.

Returns:: The end iterator.

Public Static Functions

static Self fromList(const List<Key> &values)

Create a hash set from a list.

Parameters:: values – The list of keys.
Returns:: A new hash set with unique keys.

Friends

inline friend void swap(HashSet &first, HashSet &second) noexcept

Swap two hash sets.

Parameters:

first – The first hash set.
second – The second hash set.

template<typename tElement, typename tSelf> class List

A copy-on-write list container with Erbsland-style element access and algorithms.

See: General Utilities

Template Parameters:

tElement – The element type stored in this list.
tSelf – Internal CRTP type used by derived public list types.

Subclassed by erbsland::text::impl::StringList< U32String >

Public Types

using Element = tElement : The stored element type.

using Raw = std::vector<Element>: The wrapped standard container.

using Storage = mem::CowManualStorage<Raw>: The COW storage type.

using Index = unit::ItemIndex : The element index type.

using Count = unit::ItemCount : The element count type.

using Range = unit::ItemRange : The element range type.

using Self = std::conditional_t<std::is_void_v<tSelf>, List<Element>, tSelf>: The fluent return type.

using value_type = Element : Standard container value type.

using const_iterator = Raw::const_iterator: Standard const iterator type.

Public Functions

List(): Create an empty list.

explicit List(std::initializer_list<Element> values)

Create a list from an initializer list.

Parameters:: values – The elements to copy.

explicit List(Element value)

Create a list with a single element.

Parameters:: value – The element to store.

List(Count count, const Element &value)

Create a list with repeated elements.

Parameters:

count – The number of elements.
value – The element value to repeat.

explicit List(const Raw &raw)

Create a list from a standard vector.

Parameters:: raw – The vector to copy.

explicit List(Raw &&raw)

Create a list from a standard vector, taking ownership.

Parameters:: raw – The vector to move.

Self operator+(const Self &other) const

Concatenate two lists.

Parameters:: other – The list to append.
Returns:: A new list containing all elements.

Self operator+(const Element &value) const

Append an element to a list.

Parameters:: value – The element to append.
Returns:: A new list with the element added.

Self operator+(Element &&value) const

Append an element to a list, taking ownership of the value.

Parameters:: value – The element to append.
Returns:: A new list with the element added.

Self &operator+=(const Self &other)

Append another list to this list.

Parameters:: other – The list to append.
Returns:: A reference to this list.

Self &operator+=(const Element &value)

Append an element to this list.

Parameters:: value – The element to append.
Returns:: A reference to this list.

Self &operator+=(Element &&value)

Append an element to this list, taking ownership of the value.

Parameters:: value – The element to append.
Returns:: A reference to this list.

std::strong_ordering operator<=>(const Self &other) const

Compare two lists lexicographically.

Parameters:: other – The list to compare with.
Returns:: A three-way comparison result.

bool operator==(const Self &other) const

Test two lists for equality.

Parameters:: other – The list to compare with.
Returns:: true if both lists have the same elements in the same order.

const Raw &toRawValue() const noexcept

Return a reference to the underlying standard vector.

Returns:: The wrapped vector.

Raw toStdVector() const

Convert to a standard vector.

Returns:: A copy of the list as a std::vector.

std::set<Element> toStdSet() const

Convert to a standard set.

Returns:: A copy of the list as a std::set.

Count count() const noexcept

Return the number of elements.

Returns:: The element count.

template<typename Function> Count countIf(Function function) const

Count all elements matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: The number of matching elements.

Element get(Index index) const

Get an element by index.

Parameters:: index – The element index.
Returns:: A copy of the element.

Element get(Index index, const Element &defaultValue) const

Get an element by index, with a default value.

Parameters:

index – The element index.
defaultValue – The value to return if the index is out of range.

Returns:

The element, or the default value.

const Element &getRef(Index index) const

Get a const reference to an element or a shared default element.

A stored-element reference remains valid only until this list is modified or destroyed. The immutable default element returned for an invalid index has static lifetime.

Parameters:: index – The element index.
Returns:: A const reference to the element, or to a default-constructed element if index is invalid.

const Element &getRefOrThrow(Index index) const

Get a const reference to an element by index.

The returned reference is borrowed from this list and remains valid only until this list is modified or destroyed.

Parameters:: index – The element index.
Throws:: err::OutOfRangeError – If index is invalid or outside this list.
Returns:: A const reference to the element.

Element first() const

Get the first element.

Returns:: A copy of the first element.

Element last() const

Get the last element.

Returns:: A copy of the last element.

Self &set(Index index, const Element &value)

Set an element at a given index.

Parameters:

index – The element index.
value – The new element value.

Returns:

A reference to this list.

Self &set(Index index, Element &&value)

Set an element at a given index, taking ownership of the value.

Parameters:

index – The element index.
value – The new element value.

Returns:

A reference to this list.

Self &resize(Count count)

Resize the list.

Parameters:: count – The new element count.
Returns:: A reference to this list.

Self &resize(Count count, const Element &value)

Resize the list, filling new elements with a value.

Parameters:

count – The new element count.
value – The value for new elements.

Returns:

A reference to this list.

Self &reserve(Count count)

Reserve capacity.

Parameters:: count – The minimum capacity to reserve.
Returns:: A reference to this list.

Count capacity() const noexcept

Return the current capacity.

Returns:: The current capacity.

Self &shrinkToFit()

Shrink the underlying storage to fit.

Returns:: A reference to this list.

Self &clear()

Remove all elements.

Returns:: A reference to this list.

Self &swap(Self &other) noexcept

Swap with another list.

Parameters:: other – The list to swap with.
Returns:: A reference to this list.

std::pair<Element, Self> sliceFirst() const

Split the list into first element and the rest.

Returns:: A pair of the first element and the remaining list.

std::pair<Element, Self> sliceLast() const

Split the list into the last element and the rest.

Returns:: A pair of the last element and the remaining list.

Self slice(Range range) const

Extract a sub-list from a range.

Parameters:: range – The element range to extract.
Returns:: A new list containing the sliced elements.

Self prefix(Count count) const

Get the first count elements.

Parameters:: count – The number of elements to take.
Returns:: A new list with the prefix.

Self suffix(Count count) const

Get the last count elements.

Parameters:: count – The number of elements to take.
Returns:: A new list with the suffix.

Self &remove(Index index)

Remove an element at a given index.

Parameters:: index – The index to remove.
Returns:: A reference to this list.

Self &remove(Range range)

Remove elements in a range.

Parameters:: range – The element range to remove.
Returns:: A reference to this list.

template<typename Function> Self &removeIf(Function function)

Remove all elements matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: A reference to this list.

Self removed(Index index) const

Return a copy with one element removed.

Parameters:: index – The index to remove.
Returns:: A new list without the element.

Self removed(Range range) const

Return a copy with a range removed.

Parameters:: range – The element range to remove.
Returns:: A new list without the range.

template<typename Function> Self removedIf(Function function) const

Return a copy without elements matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: A new list without matching elements.

Self &removeFirst()

Remove the first element.

Returns:: A reference to this list.

Self &removeLast()

Remove the last element.

Returns:: A reference to this list.

Element take(Index index)

Take an element at a given index.

Parameters:: index – The index to take from.
Returns:: The element at the index.

Self take(Range range)

Take all elements in a range.

Parameters:: range – The range to remove and return.
Returns:: A list containing the taken elements.

template<typename Function> Self takeIf(Function function)

Take all elements matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: A list containing the taken elements.

Element takeFirst()

Take the first element.

Returns:: The first element.

Element takeLast()

Take the last element.

Returns:: The last element.

template<typename Function> LoopResult forEach(Function function) const

Call a function for every element.

Parameters:: function – The function called as function(value) or function(value, index). If both forms are supported, the indexed form is used.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachReverse(Function function) const

Call a function for every element in reverse order.

Parameters:: function – The function called as function(value) or function(value, index). If both forms are supported, the indexed form is used.
Returns:: The result of the iteration.

template<typename Function> Self &map(Function function)

Replace every element with the result of a function.

Parameters:: function – The function used to map elements.
Returns:: A reference to this list.

template<typename Function> Self mapped(Function function) const

Return a copy with every element mapped through a function.

Parameters:: function – The function used to map elements.
Returns:: A mapped copy of the list.

Self &reverse()

Reverse the list in place.

Returns:: A reference to this list.

Self reversed() const

Return a reversed copy.

Returns:: A new list in reverse order.

Self &collapse()

Collapse consecutive duplicate elements.

Returns:: A reference to this list.

Self collapsed() const

Return a copy with consecutive duplicate elements collapsed.

Returns:: A new list with duplicate runs collapsed.

Self &sort()

Sort the list in place.

Returns:: A reference to this list.

template<typename Function> Self &sort(Function function)

Sort the list in place using a comparison function.

Parameters:: function – The comparison function.
Returns:: A reference to this list.

Self sorted() const

Return a sorted copy of the list.

Returns:: A new sorted list.

template<typename Function> Self sorted(Function function) const

Return a sorted copy using a comparison function.

Parameters:: function – The comparison function.
Returns:: A new sorted list.

Index findFirst(const Element &value) const

Find the first occurrence of a value.

Parameters:: value – The value to search for.
Returns:: The index of the first occurrence.

Index findFirst(const Element &value, Index start) const

Find the first occurrence of a value starting from an index.

Parameters:

value – The value to search for.
start – The index to start searching from.

Returns:

The index of the first occurrence.

template<typename Function> Index findFirstIf(Function function) const

Find the first element matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: The index of the first matching element.

template<typename Function> Index findFirstIf(Function function, Index start) const

Find the first element matching a predicate starting from an index.

Parameters:

function – The predicate called for every element.
start – The index to start searching from.

Returns:

The index of the first matching element.

Index findLast(const Element &value) const

Find the last occurrence of a value.

Parameters:: value – The value to search for.
Returns:: The index of the last occurrence.

Index findLast(const Element &value, Index start) const

Find the last occurrence of a value starting backwards from an index.

Parameters:

value – The value to search for.
start – The index to start searching from.

Returns:

The index of the last occurrence.

template<typename Function> Index findLastIf(Function function) const

Find the last element matching a predicate.

Parameters:: function – The predicate called for every element.
Returns:: The index of the last matching element.

template<typename Function> Index findLastIf(Function function, Index start) const

Find the last element matching a predicate starting backwards from an index.

Parameters:

function – The predicate called for every element.
start – The index to start searching from.

Returns:

The index of the last matching element.

Self &insert(Index index, const Element &value)

Insert an element at a given index.

Parameters:

index – The index to insert at.
value – The element to insert.

Returns:

A reference to this list.

Self &insert(Index index, Element &&value)

Insert an element at a given index, taking ownership of the value.

Parameters:

index – The index to insert at.
value – The element to insert.

Returns:

A reference to this list.

Self &insert(Index index, const Self &other)

Insert another list at a given index.

Parameters:

index – The index to insert at.
other – The list to insert.

Returns:

A reference to this list.

Self &append(const Element &value)

Append an element.

Parameters:: value – The element to append.
Returns:: A reference to this list.

Self &append(Element &&value)

Append an element, taking ownership of the value.

Parameters:: value – The element to append.
Returns:: A reference to this list.

Self &append(const Self &other)

Append another list.

Parameters:: other – The list to append.
Returns:: A reference to this list.

Self &prepend(const Element &value)

Prepend an element.

Parameters:: value – The element to prepend.
Returns:: A reference to this list.

Self &prepend(Element &&value)

Prepend an element, taking ownership of the value.

Parameters:: value – The element to prepend.
Returns:: A reference to this list.

Self &prepend(const Self &other)

Prepend another list.

Parameters:: other – The list to prepend.
Returns:: A reference to this list.

bool isEmpty() const

Test if this list is empty.

Returns:: true if the list has no elements.

std::strong_ordering compare(const Self &other) const

Compare two lists lexicographically.

Parameters:: other – The list to compare with.
Returns:: A three-way comparison result.

bool contains(const Element &value) const

Test if the list contains a value.

Parameters:: value – The value to search for.
Returns:: true if the value is present.

template<typename Function> bool allOf(Function function) const

Test if all elements match a predicate.

Parameters:: function – The predicate called for every element.
Returns:: true if all elements match.

template<typename Function> bool anyOf(Function function) const

Test if any element matches a predicate.

Parameters:: function – The predicate called for every element.
Returns:: true if at least one element matches.

template<typename Function> bool noneOf(Function function) const

Test if no element matches a predicate.

Parameters:: function – The predicate called for every element.
Returns:: true if no element matches.

const_iterator begin() const noexcept

Return an iterator to the first element.

Returns:: The begin iterator.

const_iterator end() const noexcept

Return an iterator past the last element.

Returns:: The end iterator.

Friends

inline friend Self operator+(const Element &value, const Self &list)

Prepend an element to a list.

Parameters:

value – The element to prepend.
list – The list to prepend to.

Returns:

A new list with the element added at the front.

inline friend Self operator+(Element &&value, const Self &list)

Prepend an element to a list, taking ownership of the value.

Parameters:

value – The element to prepend.
list – The list to prepend to.

Returns:

A new list with the element added at the front.

inline friend void swap(List &first, List &second) noexcept

Swap two lists.

Parameters:

first – The first list.
second – The second list.

enum class erbsland::util::LoopResult : uint8_t

A generic result why a loop has ended.

Values:

enumerator Success

The main end condition was reached.

for strings: the end of the string was reached.
for parsers: the end condition was reached.

enumerator Stopped: The read function requested a stop before the end condition was reached.

enumerator LimitReached: A maximum number of iterations/chars was reached, but the loop could potentially continue.

enumerator EndOfData: The end of the data was reached.

enumerator Error: The loop function reported an error.

enum class erbsland::util::LoopStatus : uint8_t

The reported status of a loop function.

Values:

enumerator Continue: Continue looping.

enumerator Stop: Stop the loop early in a regular way.

enumerator Error: Stop the loop, reporting an error.

template<typename tKey, typename tValue, typename tCompare = std::less<tKey>, typename tSelf = void> class Map

A copy-on-write ordered key/value container with Erbsland-style access and algorithms.

See: General Utilities

Template Parameters:

tKey – The key type.
tValue – The value type.
tCompare – The key comparison type.
tSelf – Internal CRTP type used by derived public map types.

Subclassed by erbsland::text::impl::StringMap< text::String >, erbsland::text::impl::StringMap< std::optional< erbsland::text::U8String > >, erbsland::text::impl::StringMap< Value >, erbsland::text::impl::StringMap< FilterFn >, erbsland::text::impl::StringMap< ConstCompiledBlockPtr >, erbsland::text::impl::StringMap< ConstBlockChainPtr >, erbsland::text::impl::StringMap< bool >, erbsland::text::impl::StringMap< ConstCompiledLayoutPtr >

Public Types

using Key = tKey : The key type.

using Value = tValue : The value type.

using Entry = std::pair<Key, Value>: One map entry.

using Compare = tCompare : The key comparison type.

using Raw = std::map<Key, Value, Compare>: The wrapped standard container.

using Storage = mem::CowManualStorage<Raw>: The COW storage type.

using Count = unit::ItemCount : The element count type.

using Self = std::conditional_t<std::is_void_v<tSelf>, Map<Key, Value, Compare>, tSelf>: The fluent return type.

using key_type = Key : Standard container key type.

using mapped_type = Value : Standard mapped value type.

using value_type = Entry : Standard container value type.

using const_iterator = Raw::const_iterator: Standard const iterator type.

Public Functions

Map(): Create an empty map.

explicit Map(std::initializer_list<Entry> values)

Create a map from an initializer list.

Parameters:: values – The key-value pairs to insert.

explicit Map(const Raw &raw)

Create a map from a standard map.

Parameters:: raw – The map to copy.

explicit Map(Raw &&raw)

Create a map from a standard map, taking ownership.

Parameters:: raw – The map to move.

const Raw &toRawValue() const noexcept

Return a reference to the underlying standard map.

Returns:: The wrapped map.

Raw toStdMap() const

Convert to a standard map.

Returns:: A copy of the wrapped map.

std::unordered_map<Key, Value> toStdUnorderedMap() const

Convert to a standard unordered map.

Returns:: An unordered map with all entries.

std::vector<Key> toStdKeyVector() const

Convert keys to a standard vector.

Returns:: A vector with all keys.

std::vector<Entry> toStdVector() const

Convert entries to a standard vector.

Returns:: A vector with all entries.

Set<Key, Compare> toKeySet() const

Convert keys to an ordered set.

Returns:: A set with all keys.

HashSet<Key> toKeyHashSet() const

Convert keys to a hash set.

Returns:: A hash set with all keys.

Set<Value> toValueSet() const

Convert values to an ordered set.

Returns:: A set with all values.

HashSet<Value> toValueHashSet() const

Convert values to a hash set.

Returns:: A hash set with all values.

Count count() const noexcept

Return the number of entries.

Returns:: The entry count.

template<typename Function> Count countIf(Function function) const

Count all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: The number of matching entries.

template<typename Function> Count countIfKey(Function function) const

Count all keys matching a predicate.

Parameters:: function – The predicate called with each key.
Returns:: The number of matching keys.

template<typename Function> Count countIfValue(Function function) const

Count all values matching a predicate.

Parameters:: function – The predicate called with each value.
Returns:: The number of matching values.

std::optional<Value> get(const Key &key) const

Get a value by key.

Parameters:: key – The key to look up.
Returns:: The value, or std::nullopt if not found.

Value get(const Key &key, const Value &defaultValue) const

Get a value by key, with a default.

Parameters:

key – The key to look up.
defaultValue – The value to return if not found.

Returns:

The value, or the default.

Entry first() const

Get the first (smallest key) entry.

Returns:: A copy of the first entry.

Entry last() const

Get the last (largest key) entry.

Returns:: A copy of the last entry.

List<Key> toKeyList() const

Convert keys to a list.

Returns:: A list with all keys.

List<Value> toValueList() const

Convert values to a list.

Returns:: A list with all values.

List<Entry> toList() const

Convert entries to a list.

Returns:: A list with all entries.

Self &reserve(Count count)

Reserve capacity.

Parameters:: count – The minimum capacity to reserve.
Returns:: A reference to this map.

Count capacity() const noexcept

Return the current capacity.

Returns:: The current capacity.

Self &shrinkToFit()

Shrink the underlying storage to fit.

Returns:: A reference to this map.

Self &clear()

Remove all entries.

Returns:: A reference to this map.

Self &swap(Self &other) noexcept

Swap with another map.

Parameters:: other – The map to swap with.
Returns:: A reference to this map.

Self &remove(const Key &key)

Remove an entry by key.

Parameters:: key – The key to remove.
Returns:: A reference to this map.

template<typename Function> Self &removeIf(Function function)

Remove all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A reference to this map.

template<typename Function> Self &removeIfKey(Function function)

Remove all entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A reference to this map.

template<typename Function> Self &removeIfValue(Function function)

Remove all entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A reference to this map.

Self removed(const Key &key) const

Return a map without one key.

Parameters:: key – The key to remove.
Returns:: A new map without the key.

template<typename Function> Self removedIf(Function function) const

Return a map without entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A new map without matching entries.

template<typename Function> Self removedIfKey(Function function) const

Return a map without entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A new map without matching keys.

template<typename Function> Self removedIfValue(Function function) const

Return a map without entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A new map without matching values.

Value take(const Key &key)

Take a value by key.

Parameters:: key – The key to take.
Returns:: The value associated with the key.

template<typename Function> Self takeIf(Function function)

Take all entries matching a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: A map containing the taken entries.

template<typename Function> Self takeIfKey(Function function)

Take all entries whose key matches a predicate.

Parameters:: function – The predicate called with each key.
Returns:: A map containing the taken entries.

template<typename Function> Self takeIfValue(Function function)

Take all entries whose value matches a predicate.

Parameters:: function – The predicate called with each value.
Returns:: A map containing the taken entries.

template<typename Function> LoopResult forEach(Function function) const

Call a function for every entry.

Parameters:: function – The function called with each entry.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachKey(Function function) const

Call a function for every key.

Parameters:: function – The function called with each key.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachValue(Function function) const

Call a function for every value.

Parameters:: function – The function called with each value.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachReverse(Function function) const

Call a function for every entry in reverse key order.

Parameters:: function – The function called with each entry.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachKeyReverse(Function function) const

Call a function for every key in reverse order.

Parameters:: function – The function called with each key.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachValueReverse(Function function) const

Call a function for every value in reverse key order.

Parameters:: function – The function called with each value.
Returns:: The result of the iteration.

template<typename Function> Self &mapValue(Function function)

Replace every value with the result of a function.

Parameters:: function – The function used to map values.
Returns:: A reference to this map.

template<typename Function> Self mappedValues(Function function) const

Return a copy with every value mapped through a function.

Parameters:: function – The function used to map values.
Returns:: A mapped copy of the map.

template<typename tValueFwd> Self &set(const Key &key, tValueFwd &&value)

Set a key-value pair.

Parameters:

key – The key.
value – The value.

Returns:

A reference to this map.

template<typename tValueFwd> Self &set(Key &&key, tValueFwd &&value)

Set a key-value pair, taking ownership of the key.

Parameters:

key – The key.
value – The value.

Returns:

A reference to this map.

template<typename tValueFwd> bool tryReplace(const Key &key, tValueFwd &&value)

Try to replace an existing value.

Parameters:

key – The key to replace.
value – The new value.

Returns:

true if the key existed and was replaced.

template<typename tValueFwd> bool tryReplace(Key &&key, tValueFwd &&value)

Try to replace an existing value, taking ownership of the key when replaced.

Parameters:

key – The key to replace.
value – The new value.

Returns:

true if the key existed and was replaced.

template<typename tValueFwd> bool tryInsert(const Key &key, tValueFwd &&value)

Try to insert a new entry.

Parameters:

key – The key.
value – The value.

Returns:

true if the key was not already present.

template<typename tValueFwd> bool tryInsert(Key &&key, tValueFwd &&value)

Try to insert a new entry, taking ownership of the key when inserted.

Parameters:

key – The key.
value – The value.

Returns:

true if the key was not already present.

bool compare(const Self &other) const

Test if two maps contain the same entries.

Parameters:: other – The map to compare with.
Returns:: true if both maps have the same key-value pairs.

bool compareKeys(const Self &other) const

Test if two maps contain the same keys.

Parameters:: other – The map to compare with.
Returns:: true if both maps have the same keys.

bool contains(const Key &key) const

Test if the map contains a key.

Parameters:: key – The key to search for.
Returns:: true if the key is present.

template<typename Function> bool allOf(Function function) const

Test if all entries match a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if all entries match.

template<typename Function> bool anyOf(Function function) const

Test if any entry matches a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if at least one entry matches.

template<typename Function> bool noneOf(Function function) const

Test if no entry matches a predicate.

Parameters:: function – The predicate called with each entry.
Returns:: true if no entry matches.

const_iterator begin() const noexcept

Return an iterator to the first entry.

Returns:: The begin iterator.

const_iterator end() const noexcept

Return an iterator past the last entry.

Returns:: The end iterator.

Friends

inline friend void swap(Map &first, Map &second) noexcept

Swap two maps.

Parameters:

first – The first map.
second – The second map.

class Result

A type safe, extendable result type.

Using Result instead of bool makes user code more readable and easier to understand.
Resolves to one byte, same size as bool.
May be extended to transport more states and more information.
Supports multiple success and failure states. Internally uses a single byte to store the result value. Success values are in the range [0, 127], failure values are in the range [128, 255], counting down from 255. The first success value is therefore 0, and the last success value is 127. Read the documentation for more information how to write custom result types.

Subclassed by erbsland::cterm::ReadLineStatus, erbsland::network::NetworkSendStatus, erbsland::path::PathWalkResult, erbsland::stream::StreamCloseStatus, erbsland::stream::StreamPositionStatus, erbsland::stream::StreamReadStatus, erbsland::stream::StreamWaitStatus, erbsland::stream::StreamWriteStatus, erbsland::text::TextWalkResult, erbsland::util::ResultWithData< tData, tStatus >

Public Functions

inline constexpr Result(const Value value)

Create a new result.

Parameters:: value – The value of the result.

inline bool operator==(const Result &other) const: Compare result values for equality.

inline bool operator!=(const Result &other) const: Compare result values for inequality.

inline constexpr bool isSuccessful() const: Test if the call was successful.

inline constexpr bool isFailure() const: Test if the call has failed.

Public Static Attributes

static const Result Success = Result::Value::success<0>(): The canonical successful result.

static const Result Failure = Result::Value::failure<0>(): The canonical failed result.

Friends

inline friend constexpr bool isSuccessful(const Result &result): Test if the call was successful.

inline friend constexpr bool isFailure(const Result &result): Test if the call has failed.

template<typename tData, typename tStatus = Result> class ResultWithData : public erbsland::util::Result 

A result that transports additional typed data.

The result derives from its status type and keeps its success/failure semantics.

Template Parameters:

tData – The transported data type.
tStatus – The result status type.

Public Types

using Data = tData : The transported data type.

using Status = tStatus : The specialized result status type.

Public Functions

inline ResultWithData(const Status result, const Data &data)

Create a result with copied data.

Parameters:

result – The result status.
data – The data to transport.

inline ResultWithData(const Status result, Data &&data) noexcept(std::is_nothrow_move_constructible_v<Data>)

Create a result with moved data.

Parameters:

result – The result status.
data – The data to transport.

inline Status status() const noexcept: Get the specialized result status.

inline const Data &data() const noexcept: Access the transported data.

inline Data &data() noexcept: Access the transported data.

inline Data takeData() noexcept(std::is_nothrow_move_constructible_v<Data>): Take the transported data from this result.

template<typename tKey, typename tCompare, typename tSelf> class Set

A copy-on-write ordered key container with Erbsland-style access and set algorithms.

See: General Utilities

Template Parameters:

tKey – The key type.
tCompare – The key comparison type.
tSelf – Internal CRTP type used by derived public set types.

Public Types

using Key = tKey : The key type.

using Compare = tCompare : The key comparison type.

using Raw = std::set<Key, Compare>: The wrapped standard container.

using Storage = mem::CowManualStorage<Raw>: The COW storage type.

using Count = unit::ItemCount : The element count type.

using Self = std::conditional_t<std::is_void_v<tSelf>, Set<Key, Compare>, tSelf>: The fluent return type.

using key_type = Key : Standard container key type.

using value_type = Key : Standard container value type.

using const_iterator = typename Raw::const_iterator: Standard const iterator type.

Public Functions

Set(): Create an empty set.

explicit Set(std::initializer_list<Key> values)

Create a set from an initializer list.

Parameters:: values – The keys to insert.

explicit Set(const Raw &raw)

Create a set from a standard set.

Parameters:: raw – The set to copy.

explicit Set(Raw &&raw)

Create a set from a standard set, taking ownership.

Parameters:: raw – The set to move.

const Raw &toRawValue() const noexcept

Return a reference to the underlying standard set.

Returns:: The wrapped set.

List<Key> toList() const

Convert to a list.

Returns:: A list with all keys.

std::vector<Key> toStdVector() const

Convert to a standard vector.

Returns:: A vector with all keys.

Raw toStdSet() const

Convert to a standard set.

Returns:: A copy of the wrapped set.

std::unordered_set<Key> toStdUnorderedSet() const

Convert to a standard unordered set.

Returns:: An unordered set with all keys.

Count count() const noexcept

Return the number of elements.

Returns:: The element count.

template<typename Function> Count countIf(Function function) const

Count all keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: The number of matching keys.

Key first() const

Get the first (smallest) element.

Returns:: A copy of the first element.

Key last() const

Get the last (largest) element.

Returns:: A copy of the last element.

Self &reserve(Count count)

Reserve capacity.

Parameters:: count – The minimum capacity to reserve.
Returns:: A reference to this set.

Count capacity() const noexcept

Return the current capacity.

Returns:: The current capacity.

Self &shrinkToFit()

Shrink the underlying storage to fit.

Returns:: A reference to this set.

Self &clear()

Remove all elements.

Returns:: A reference to this set.

Self &swap(Self &other) noexcept

Swap with another set.

Parameters:: other – The set to swap with.
Returns:: A reference to this set.

Self &remove(const Key &key)

Remove a key.

Parameters:: key – The key to remove.
Returns:: A reference to this set.

bool tryRemove(const Key &key)

Try to remove a key.

Parameters:: key – The key to remove.
Returns:: true if the key was present and removed.

template<typename Function> Self &removeIf(Function function)

Remove all keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: A reference to this set.

Self removed(const Key &key) const

Return a set with a key removed.

Parameters:: key – The key to remove.
Returns:: A new set without the key.

template<typename Function> Self removedIf(Function function) const

Return a set without keys matching a predicate.

Parameters:: function – The predicate called for every key.
Returns:: A new set without matching keys.

template<typename Function> LoopResult forEach(Function function) const

Call a function for every key.

Parameters:: function – The function called for every key.
Returns:: The result of the iteration.

template<typename Function> LoopResult forEachReverse(Function function) const

Call a function for every key in reverse order.

Parameters:: function – The function called for every key.
Returns:: The result of the iteration.

Self &unite(const Self &other)

Unite with another set (union).

Parameters:: other – The set to unite with.
Returns:: A reference to this set.

Self &intersect(const Self &other)

Intersect with another set.

Parameters:: other – The set to intersect with.
Returns:: A reference to this set.

Self &subtract(const Self &other)

Subtract another set (difference).

Parameters:: other – The set to subtract.
Returns:: A reference to this set.

Self &symmetricDifference(const Self &other)

Compute the symmetric difference with another set.

Parameters:: other – The set for the symmetric difference.
Returns:: A reference to this set.

Self unitedWith(const Self &other) const

Return the union of this set and another.

Parameters:: other – The set to unite with.
Returns:: A new set containing all elements.

Self intersectedWith(const Self &other) const

Return the intersection of this set and another.

Parameters:: other – The set to intersect with.
Returns:: A new set containing common elements.

Self subtractedBy(const Self &other) const

Return the difference of this set from another.

Parameters:: other – The set to subtract.
Returns:: A new set with elements of other removed.

Self symmetricDifferenceWith(const Self &other) const

Return the symmetric difference with another set.

Parameters:: other – The set for the symmetric difference.
Returns:: A new set with elements unique to either set.

Self &insert(const Key &key)

Insert a key.

Parameters:: key – The key to insert.
Returns:: A reference to this set.

Self &insert(Key &&key)

Insert a key, taking ownership of the value.

Parameters:: key – The key to insert.
Returns:: A reference to this set.

bool tryInsert(const Key &key)

Try to insert a key.

Parameters:: key – The key to insert.
Returns:: true if the key was not already present.

bool tryInsert(Key &&key)

Try to insert a key, taking ownership of the value.

Parameters:: key – The key to insert.
Returns:: true if the key was not already present.

bool compare(const Self &other) const

Test if two sets contain the same elements.

Parameters:: other – The set to compare with.
Returns:: true if both sets contain the same keys.

bool contains(const Key &key) const

Test if the set contains a key.

Parameters:: key – The key to search for.
Returns:: true if the key is present.

template<typename Function> bool allOf(Function function) const

Test if all keys match a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if all keys match.

template<typename Function> bool anyOf(Function function) const

Test if any key matches a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if at least one key matches.

template<typename Function> bool noneOf(Function function) const

Test if no key matches a predicate.

Parameters:: function – The predicate called for every key.
Returns:: true if no key matches.

bool isSubsetOf(const Self &other) const

Test if this set is a subset of another.

Parameters:: other – The superset to compare with.
Returns:: true if all elements are in other.

bool isSupersetOf(const Self &other) const

Test if this set is a superset of another.

Parameters:: other – The subset to compare with.
Returns:: true if all elements of other are in this set.

bool isDisjointWith(const Self &other) const

Test if this set has no elements in common with another.

Parameters:: other – The set to compare with.
Returns:: true if the sets share no elements.

bool intersects(const Self &other) const

Test if this set shares any elements with another.

Parameters:: other – The set to compare with.
Returns:: true if there is at least one common element.

const_iterator begin() const noexcept

Return an iterator to the first key.

Returns:: The begin iterator.

const_iterator end() const noexcept

Return an iterator past the last key.

Returns:: The end iterator.

Public Static Functions

static Self fromList(const List<Key> &values)

Create a set from a list.

Parameters:: values – The list of keys.
Returns:: A new set with unique keys.

Friends

inline friend void swap(Set &first, Set &second) noexcept

Swap two sets.

Parameters:

first – The first set.
second – The second set.