Utilities API Guidelines

Primary Types

List❮Value❯ // copy-on-write sequential container
Set❮Key❯, HashSet❮Key❯ // copy-on-write ordered and unordered sets
Map❮Entry❯, HashMap❮Entry❯ // copy-on-write ordered and unordered maps
EnumFlags❮Enum❯ // type-safe enum-class flag set
Result, ResultWithData❮Data❯ // typed status and payload-bearing result
CoGenerator❮Value❯ // lazy synchronous pull generator
CoTask❮Value❯ // eagerly started move-only coroutine task
CoAsyncGenerator❮Value❯ // lazy asynchronous single-pass generator

Secondary Types

LoopResult // completion reason returned by visitors and parsers
LoopStatus // continue, regular stop, or error request from a loop callback

Pattern Definitions

E = ❮Element❯/❮Entry❯ // element or map-entry value
K = ❮Key❯ // map or set key
R = ❮RawContainer❯ // wrapped standard container
V = ❮Value❯ // stored or mapped value

Hash Patterns

combineHash(first, second) -> std::size_t // combine two computed hashes
advanceHash(hash, value) // add one value to an existing hash
createHash(first, rest...) -> std::size_t // combine hashes for one or more values

Common Container Patterns

T([values]) // create an empty container or copy compatible values
o.toRawValue() -> R // cross the explicit standard-container boundary
o.count()/countIf(function) -> unit::ItemCount // count elements or predicate matches
o.first()/last() -> E // access an iteration-boundary value or its default
o.clear()/swap(other) -> T& // remove or exchange contents
o.remove/removeIf(selector) -> T& // remove selected data in place
o.removed/removedIf(selector) -> T // return a copy without selected data
o.forEach(function) -> LoopResult // visit elements with container-specific callback arguments
o.contains(value-or-key) -> bool // test membership
o.allOf/anyOf/noneOf(function) -> bool // test a predicate over elements
o.begin()/end() -> T // provide minimal standard iteration

List Patterns

o.get(index[, fallback]) -> E // access a value or fallback
o.getRef(index) -> const E& // borrow a value or a shared immutable default
o.getRefOrThrow(index) -> const E& // borrow a value or throw for an invalid index
o.set(index, value) -> T& // replace a valid index
o.resize/reserve/shrinkToFit(count) -> T& // manage sequential storage
o.slice/prefix/suffix(range-or-count) -> T // copy a selected range
o.take(index-or-range) -> E // remove and return selected data
o.takeIf(function) -> T // remove and return predicate matches
o.insert/append/prepend(position, value-or-list) -> T& // add sequential values
o.map/reverse/sort([function]) -> T& // transform ordering or values in place
o.mapped/reversed/sorted([function]) -> T // return transformed values
o.findFirst/findLast(value-or-function[, start]) -> unit::ItemIndex // locate a value or predicate match
o.toStdVector()/toStdSet() -> R // explicitly copy into a standard container

Set Patterns

T::fromList(values) -> T // create from an Erbsland Core list
o.insert(key)/remove(key) -> T& // mutate membership
o.tryInsert/tryRemove(key) -> bool // mutate and report whether membership changed
o.unite/intersect/subtract/symmetricDifference(other) -> T& // apply a set relation in place
o.unitedWith/intersectedWith/subtractedBy/symmetricDifferenceWith(other) -> T // return a set relation
o.isSubsetOf/isSupersetOf/isDisjointWith/intersects(other) -> bool // test set relations
o.toList()/toStd❮Container❯() -> T // explicitly copy into another container

Map Patterns

o.get(key[, fallback]) -> V // access a mapped value or fallback
o.set(key, value) -> T& // insert or replace a mapping
o.tryInsert/tryReplace(key, value) -> bool // conditionally mutate a mapping
o.take(key) -> V // remove and return a mapped value or its default
o.removeIf❮Part❯/takeIf❮Part❯(function) -> T // remove key, value, or entry matches
o.forEach❮Part❯(function) -> LoopResult // visit entries, keys, or values
o.mapValue(function) -> T& // transform mapped values in place
o.mappedValues(function) -> T // return transformed mapped values
o.to❮Part❯List()/to❮Part❯Set() -> T // copy keys, values, or entries into a Core container
o.toStd❮Container❯() -> R // explicitly copy into a standard container

Flag Patterns

T([flag-or-flags]) // create an empty or initialized flag set
T::fromRawValue(value) -> T // import raw flag bits
o.toRawValue() -> V // export raw flag bits
o.isEmpty()/hasAny()/isSet(flag) -> bool // test flag state
o.contains/intersects(flags) -> bool // test complete or partial overlap
o.set/clear([flags]) // add or remove bits
o.replaceMasked(flags, mask) // replace selected bits

Result Patterns

o.isSuccessful()/isFailure() -> bool // test status without implicit conversion
T(status, data) // create a payload-bearing result
o.status()/data() -> T // inspect status or payload
o.takeData() -> V // move out transported data

Coroutine Patterns

T::run(function) -> CoTask❮V❯ // eagerly run bounded work on the coroutine worker service
o.isComplete() -> bool // poll task completion
o.result()/takeResult() -> V // inspect or consume a task result
o.cancel() // request cancellation and release the task handle
o.next() -> T // produce or await the next optional value