Use this reference to choose an operation for an existing collection. Start with the overview for eager usage, Lazy Collections for evaluation timing, or Fallible Collections for error policy.
Availability labels use E for eager Slice or Map, L for LazySlice
or LazyMap, and T for TryLazySlice or TryLazyMap. Streaming L and T
operations defer work until traversal. Terminal calls consume immediately;
buffering exceptions are stated beside the method. T callbacks that can fail
return an additional error, and terminal methods return an additional error.
Unless named All, terminals stop at the first error. Failed yielded values
must be ignored; callbacks do not receive source errors.
Import arkoren.dev/foundation/collection. Entries use these independent
application values and predicates:
type Order struct {
ID string
Zone string
Units int
Ready bool
}
orders := collection.NewSlice([]Order{
{ID: "ord-41", Zone: "north", Units: 3, Ready: true},
{ID: "ord-42", Zone: "south", Units: 1, Ready: false},
{ID: "ord-43", Zone: "north", Units: 2, Ready: true},
})
capacity := collection.NewMap(map[string]int{"north": 8, "south": 0})
ready := func(_ int, order Order) bool {
return order.Ready
}
zone := func(_ int, order Order) string {
return order.Zone
}Examples are focused fragments, not consecutive declarations in one scope.
Map result comments describe entries, not a guaranteed display order. A slice
callback receives (index, item); a map callback receives (key, value).
Fallible callback indexes follow the success rules,
not stable source identities.
Creating Collections
NewSlice,NewMap: wrap in-memory containers.NewSliceAs,NewMapAs: accept named containers.NewLazySlice,NewLazyMap: wrap infallible iterators.NewTryLazySlice,NewTryLazyMap,NewMapEntry: expose fallible sources.
NewSlice
NewSlice wraps a []T without copying: collection.NewSlice([]Order{{ID: "ord-44"}}).
The wrapper, original slice, and Items result share storage.
NewMap
NewMap wraps a map[K]V without copying:
collection.NewMap(map[string]int{"north": 8}). Keys must be comparable.
Nil eager maps support reads but still panic on indexed writes.
NewSliceAs
NewSliceAs accepts a named slice type. With type Orders []Order, use
collection.NewSliceAs(Orders{{ID: "ord-44"}}). It returns Slice[Order]
without copying; ItemsAs converts back to a named type.
NewMapAs
NewMapAs is the named-map counterpart of NewMap. With
type Capacity map[string]int, use collection.NewMapAs(Capacity{"north": 8}).
NewLazySlice
NewLazySlice retains an (index, item) iterator. For a standard-library
slices import, collection.NewLazySlice(slices.All(orders.Items())) wraps
the same source data without consuming it.
Supply a non-nil function for all four iterator constructors. Nil is not an empty iterator and panics on traversal. Sources must honor false yields and own their cleanup and cancellation.
NewLazyMap
NewLazyMap retains an iter.Seq2[K, V]. With the standard-library maps
package, collection.NewLazyMap(maps.All(capacity.Items())) wraps a Go map
with unspecified order. It does not copy or traverse it.
NewTryLazySlice
NewTryLazySlice retains an (item, error) iterator. A one-record source is:
source := collection.NewTryLazySlice(func(yield func(Order, error) bool) {
yield(Order{ID: "ord-44"}, nil)
})No work runs yet. source.Items() returns that order and nil error. A source
that yields more records must stop after a false yield.
NewTryLazyMap
NewTryLazyMap retains an iterator over (MapEntry, error) pairs:
source := collection.NewTryLazyMap(func(yield func(collection.MapEntry[string, int], error) bool) {
yield(collection.NewMapEntry("north", 8), nil)
})source.Items() returns north: 8 and nil error. Ignore entries paired with
non-nil errors.
NewMapEntry
NewMapEntry constructs a typed pair: collection.NewMapEntry("north", 8)
has Key == "north" and Value == 8. The equivalent struct is
collection.MapEntry[string, int]{Key: "north", Value: 8}.
Changing Evaluation
Lazy
Slice, Map · E
Lazy returns an iterator over shared source data. For example,
orders.Lazy().Take(1).Items() collects only ord-41. Conversion does not
copy elements, run callbacks, or cache a result.
Try
Slice, Map · E L
Try exposes successful values through the fallible lazy form. For example,
orders.Try().Items() returns the orders and nil error. Later transformation
callbacks can return errors; conversion itself consumes nothing.
Eager
Slice, Map · L T
Eager collects into an eager wrapper: orders.Lazy().Take(1).Eager() returns
a Slice[Order] containing ord-41. T returns (collection, error) and keeps
only the successful prefix before the first error. Outer result storage is new;
element copies remain shallow.
EagerAll
Slice, Map · T
EagerAll is the continuing counterpart of Eager:
snapshot, err := orders.Try().EagerAll(). It retains successes and joins
errors with errors.Join; it cannot retry or resume a terminal source.
Selecting Records
Filter
Slice, Map · E L T
Filter retains matching values in source order: orders.Filter(ready) keeps
ord-41 and ord-43. E allocates independent shallow result storage. On T,
source and predicate errors are forwarded, not filtered out.
Reject
Slice, Map · E L T
Reject retains values for which the predicate is false:
orders.Reject(ready) keeps ord-42. It is the inverse selection of
Filter, not an alias; T still forwards errors unchanged.
Unique
Slice · E L T; Map · L T
Unique keeps the first slice item for each comparable callback key:
orders.Unique(zone) keeps ord-41 and ord-42. Lazy forms retain a seen-key
set per traversal. On lazy maps, capacity.Lazy().Unique() takes no callback
and keeps the first entry per key. Materialization without Unique keeps the
last duplicate instead.
Only
Map · E L T
Only retains listed keys: capacity.Only("north") contains north: 8.
T forwards all source errors, even if the associated key would be excluded.
Except
Map · E L T
Except excludes listed keys: capacity.Except("south") contains north: 8.
Like Only, it does not hide source errors on T.
Reshaping Values
Map,FlatMap,MapValues,MapKeys: change value or key types.Sort,Reverse,Concat,Merge: order or combine collections.
Map
Slice · E L T
Map transforms each item and can change its type:
ids := orders.Map(func(_ int, order Order) string {
return order.ID
})ids contains ord-41, ord-42, and ord-43, in order. T callbacks return
(value, error) instead; a failed conversion yields an error rather than a value.
FlatMap
Slice · E L T
FlatMap expands each item into zero or more values, preserving source and
expansion order:
labels := orders.Take(1).FlatMap(func(_ int, order Order) []string {
return []string{order.ID, order.Zone}
})labels contains ord-41 and north. A nil or empty expansion contributes
no values. T callbacks return an additional error.
MapValues
Map · E L T
MapValues retains keys and transforms values, possibly to a new type:
available := capacity.MapValues(func(_ string, slots int) bool {
return slots > 0
})available contains north: true and south: false.
MapKeys
Map · E L T
MapKeys retains values and transforms keys. With strings imported:
labels := capacity.MapKeys(func(name string, _ int) string {
return strings.ToUpper(name)
})labels contains NORTH: 8 and SOUTH: 0. Colliding keys keep the last
materialized value. A Go map’s unspecified order makes that winner unspecified;
lazy sources can retain duplicates until materialization.
Sort
Slice · E L T
Sort sorts a shallow copy using a comparison function. With cmp imported:
sorted := orders.Sort(func(left, right Order) int {
return cmp.Compare(left.Units, right.Units)
})sorted contains ord-42, ord-43, then ord-41; orders keeps its order.
The comparator must define a strict weak ordering. Sorting is not stable.
L and T read the whole source on each traversal before yielding; T yields only
the error if materialization fails, discarding the prefix.
Reverse
Slice · E L T
Reverse reverses a shallow copy: orders.Reverse() begins with ord-43.
L and T buffer the whole source on each traversal; T discards partial results
if source materialization fails, as with Sort.
Concat
Slice · E L T; Map · L T
Concat appends another collection of the same form:
orders.Take(1).Concat(orders.Skip(2)) contains ord-41, then ord-43.
E copies outer storage. Lazy forms traverse the first source before the second;
early stop can avoid the second source entirely. Lazy-map duplicate keys remain
until materialization, where later entries win. Eager maps use Merge.
Merge
Map · E
Merge gives the argument precedence in independent outer storage:
capacity.Merge(collection.NewMap(map[string]int{"south": 4})) contains
north: 8 and south: 4, without changing either input. Nested references
remain shared. Nil inputs count as empty; a nil receiver merged with no entries
stays nil. Keep the return value rather than expecting receiver mutation.
Windowing Records
Take,Skip,TakeWhile,TakeUntil,SkipWhile,SkipUntil: select prefixes or suffixes.Nth,ForPage,Chunk,Sliding,Partition: select positions or groups.
Take
Slice · E L T; Map · L T
Take keeps at most a count: orders.Take(2) contains the first two orders.
E shares the source array and clamps to bounds. Nonpositive limits produce no
items and do not invoke lazy sources, including no source errors on T.
Positive T limits count successes, not errors; duplicate map entries count
separately. Reaching the last requested success stops upstream immediately.
Skip
Slice · E L T; Map · L T
Skip discards a prefix: orders.Skip(2) contains ord-43. Nonpositive
counts skip nothing; E clamps counts and shares the source array. T counts
successes while forwarding errors even inside skipped positions.
TakeWhile
Slice · E L T
TakeWhile retains a prefix until the predicate is false:
orders.TakeWhile(ready) contains ord-41. It consumes but excludes the
first false item. E copies the selected prefix; T errors do not end selection
if the consumer continues.
TakeUntil
Slice · E L T
TakeUntil retains a prefix until the predicate is true:
orders.TakeUntil(ready) is empty because the first order matches. The matching
item is excluded. It uses TakeWhile with the predicate inverted;
errors are forwarded, not inverted.
SkipWhile
Slice · E L T
SkipWhile drops the leading matches: orders.SkipWhile(ready) contains
ord-42 and ord-43. It includes the first false item and does not evaluate
the predicate on the rest. E shares the source array; T errors leave the
skipping phase unchanged.
SkipUntil
Slice · E L T
SkipUntil drops items until the predicate is true:
orders.SkipUntil(ready) contains all three orders. It includes the matching
item and uses SkipWhile with the predicate inverted. E shares
the source array.
Nth
Slice · E L T
Nth samples every nth position: orders.Nth(2) contains ord-41 and
ord-43; orders.Nth(2, 1) contains ord-42. The optional zero-based offset
defaults to zero; negative offsets clamp to zero. Offsets beyond the source
select nothing. The step must be positive or the call panics.
Every positive int step, including math.MaxInt, is valid without wrapping.
E allocates shallow result storage and returns nil for no selections. L counts
positions rather than source-supplied indexes and yields dense indexes. T
counts only successes and forwards errors even within skipped positions.
Continued traversal resumes selection progress; stopping avoids the next gap.
ForPage
Slice · E L T
ForPage selects a one-based page: orders.ForPage(2, 2) contains ord-43.
It composes Skip((page-1)*perPage) and Take(perPage) without validating
arguments or overflow. Validate positive inputs and a representable product
before use. E shares storage; T forwards errors in skipped positions. This
selects collection positions, not database result pages.
Chunk
Slice · E L T
Chunk forms consecutive groups: orders.Chunk(2) returns groups of two and
one orders. The size must be positive or the call panics. E returns
[]Slice[T] whose windows share the source array. L returns
iter.Seq2[int, []T]; T returns iter.Seq2[[]T, error]. Lazy chunks own
independent shallow storage and include the final short chunk. T errors leave
the partial chunk unchanged if traversal continues; stopping on an error does
not flush that prefix as a chunk.
Sliding
Slice · E L T
Sliding forms complete windows: orders.Sliding(2) returns windows
[ord-41, ord-42] and [ord-42, ord-43]. An optional step defaults to one;
orders.Sliding(2, 3) returns only the first window. Incomplete final windows
are omitted. Nonpositive sizes or steps panic; positive steps through
math.MaxInt do not wrap the next start.
Return types match Chunk. E windows alias the source and each other
where they overlap; lazy windows own independent shallow storage. T counts
only successes, forwarding errors even in gaps without changing window or gap
progress. Stopping on a window or error stops consumption before the next gap.
Partition
Slice · E L T
Partition splits matching and remaining items:
selected, rest := orders.Partition(ready) gives two ready orders and one
other order. E owns both shallow result slices. L and T consume at the call,
not on later traversal, and buffer replayable results. T returns two fallible
iterators: on a source or predicate error, both yield that error and no partial
partition values.
Grouping Records
GroupBy
Slice · E L T
GroupBy retains ordered groups: orders.GroupBy(zone)["north"] contains
ord-41 and ord-43. Group slices and the outer map own shallow storage;
outer-map order is unspecified. L and T consume immediately. T returns
(groups, error) and preserves successful prefix groups on failure.
KeyBy
Slice · E L T
KeyBy retains the last item for each key: orders.KeyBy(zone)["north"]
is ord-43. It allocates a new outer map. L and T consume immediately;
T returns its prefix map and the first error.
CountBy
Slice · E L T
CountBy counts observed keys: orders.CountBy(zone) contains north: 2
and south: 1. Absent map keys read as zero. L and T consume immediately;
T returns prefix counts with the first error.
Finding Answers
First,FirstWhere,Last,Get: retrieve a value and an absence flag.Has,HasAny,Contains,Every: test membership or conditions.Reduce,Len,IsEmpty,IsNotEmpty: summarize values or presence.
First
Slice · E L T
First retrieves the initial item: order, found := orders.First() gives
ord-41 and true. Empty input returns zero and false without panic. L consumes
at most one item; T returns (item, found, error) and stops even if the first
result is an error.
FirstWhere
Slice · E L T
FirstWhere retrieves the first match:
order, found := orders.FirstWhere(ready) gives ord-41 and true.
No match returns zero and false. Lazy traversal stops at the first match;
T also stops at the first source or predicate error.
Last
Slice · E L T
Last retrieves the final item: order, found := orders.Last() gives
ord-43 and true. Empty input returns zero and false. L reads the whole
source; T stops at an error and returns the last successful prefix item,
its flag, and that error.
Get
Map · E
Get checks a key: slots, found := capacity.Get("south") gives zero and
true. An absent key gives zero and false, distinguishing absence from a stored zero.
Has
Map · E
Has tests key presence: capacity.Has("south") is true even though its
stored value is zero. Lazy maps use HasAny for key searches.
HasAny
Map · E L T
HasAny tests whether any requested key exists:
capacity.HasAny("west", "south") is true. Lazy forms stop at a match;
T also stops at a source error. No requested keys returns false without
traversing the source or observing its errors.
Contains
Slice, Map · E L T
Contains tests a predicate: orders.Contains(ready) is true. It stops at
the first match, or the first source/predicate error on T. Empty input is false.
It does not accept a plain value; use standard-library slices.Contains on
Items() for direct comparable-value membership.
Every
Slice, Map · E L T
Every tests all items: orders.Every(ready) is false. It stops at the first
false result or, on T, error. Empty input returns true without invoking the predicate.
Reduce
Slice · E L T
Reduce folds items into a value of any type, starting with the initial value:
units := orders.Reduce(func(total, _ int, order Order) int {
return total + order.Units
}, 0)units is 6; empty input returns the initial zero. L and T consume at the
call. On T, source errors return the preceding accumulator; callback errors
return the accumulator supplied by that failing callback, with its error.
Len
Slice, Map · E L T
Len counts items: orders.Len() is 3. Lazy forms traverse the entire source;
T returns the successful prefix count and first error. Lazy-map duplicate
entries count separately, even if materializing would collapse their keys.
IsEmpty
Slice, Map · E L T
IsEmpty tests absence: orders.IsEmpty() is false. Lazy forms read at most
one result, not the whole source. An initial T error returns false and that
error; check the error before interpreting the boolean.
IsNotEmpty
Slice, Map · E L T
IsNotEmpty negates IsEmpty: orders.IsNotEmpty() is true.
On T, an initial error returns true with that error, not proof of a successful
item. Always check its error first.
Reading Map Parts
Keys,Values,LazyKeys,LazyValues,Invert: extract or reverse key/value roles.
Keys
Map · E · Package Function
Keys collects keys into a Slice: collection.Keys(capacity) contains
north and south, in unspecified order. With strings imported,
collection.Keys(capacity).Sort(strings.Compare) gives repeatable order.
Values
Map · E · Package Function
Values collects values into a Slice: collection.Values(capacity)
contains 8 and 0 in unspecified order. It does not establish an ordering
relationship with a separate Keys traversal.
LazyKeys
Map · L T
LazyKeys projects keys without consuming now. On L,
collection.LazyKeys(capacity.Lazy()) returns LazySlice[string]. On T,
capacity.Try().LazyKeys() is a method returning iter.Seq2[string, error],
not a collection wrapper. Both preserve duplicates and source order.
LazyValues
Map · L T
LazyValues is the value projection corresponding to LazyKeys:
collection.LazyValues(capacity.Lazy()) returns LazySlice[int];
capacity.Try().LazyValues() returns iter.Seq2[int, error].
Ignore any key or value paired with a non-nil error.
Invert
Map · E · Package Function
Invert swaps comparable keys and values: collection.Invert(capacity)
contains 8: north and 0: south. If values collide, the retained original
key is unspecified because Go-map iteration order is unspecified.
Consuming Results
Items,ItemsAs,ItemsAll,ItemsAsAll: extract or materialize containers.Iter,Each,EachAll,TapEach: consume or observe items.
Items
Slice, Map · E L T
Items returns the native container: orders.Items() is a []Order sharing
the eager source’s storage. E preserves nil versus allocated-empty storage.
L and T materialize new shallow outer storage; T returns a prefix with the first
error. Slice materialization with no successes is nil; map materialization is
allocated even when empty. Repeated lazy calls repeat traversal, not cached data.
ItemsAs
Slice, Map · E L T
ItemsAs is Items with a named container result. With
type Orders []Order, use orders.ItemsAs[Orders](). It has the same eager
aliasing, lazy allocation, and T first-error rules.
ItemsAll
Slice, Map · T
ItemsAll retains successes and joins errors:
items, err := orders.Try().ItemsAll(). It reads the full finite source while
continuation is possible. It does not retry failed reads. Empty successful
slice output is nil; map output is allocated.
ItemsAsAll
Slice, Map · T
ItemsAsAll is ItemsAll returning a named container. With
type Orders []Order, use items, err := orders.Try().ItemsAsAll[Orders]().
Errors still accompany any collected successes.
Iter
Slice, Map · E L T
Iter returns a standard iter.Seq2 without consuming now:
orders.Iter() yields (index, Order). Maps yield (key, value).
T slices yield (item, error) and T maps (MapEntry, error). Lazy collections
can also be ranged over directly. Iterator conversion changes no replay or
ownership guarantees.
Each
Slice, Map · E L T
Each consumes items for side effects. With fmt imported:
orders.Take(1).Each(func(_ int, order Order) {
fmt.Println(order.ID)
})This prints ord-41. T callbacks return an error; Each returns the first
source or callback error. Earlier side effects are not rolled back.
EachAll
Slice, Map · T
EachAll continues after source or callback errors and joins them:
err := orders.Try().EachAll(func(_ int, order Order) error {
fmt.Println(order.ID)
return nil
})It prints all three IDs and returns nil. On fallible slices its callback index advances for every successful source value, even if that callback fails. Source errors bypass the callback and do not advance its index. Continuation cannot make a terminal source recover.
TapEach
Slice, Map · E L T
TapEach observes items while passing them along unchanged:
observed := orders.Lazy().TapEach(func(_ int, order Order) {
fmt.Println(order.ID)
})Nothing prints until traversal. E instead calls the observer immediately and returns the original collection, not a copy. On T, callback failures replace their value with an error and do not advance that streaming callback’s index.
Encoding JSON
JSONSchemaType: declare eager wire shapes.MarshalJSON,MarshalJSONTo: encode containers.UnmarshalJSON,UnmarshalJSONFrom: decode containers.
Use encoding/json/v2 for ordinary json.Marshal and json.Unmarshal calls.
The compatibility method names below still use JSON v2 behavior, not legacy
encoding defaults.
JSONSchemaType
Slice, Map · E
JSONSchemaType declares the identical native container type as a
reflect.Type: orders.JSONSchemaType() is reflect.TypeFor[[]Order]().
Schema tools use that declaration for output descriptions,
including nested element metadata and byte slices’ base64 shape. It adds no
runtime rules; use the named-container adapter
for logical validation. Lazy types do not declare this protocol.
MarshalJSON
Slice, Map · E L T
MarshalJSON is the compatibility encoding method. Prefer ordinary encoding,
for example data, err := json.Marshal(capacity.Only("north")), whose successful
result is {"north":8}. Default nil non-byte slices encode as [], maps as
{}, and byte slices as base64 strings, with "" for empty storage.
Lazy forms materialize the whole finite source; encoding is not progressive item delivery. T returns the first source error instead of encoding a partial collection. Encoding errors also remain visible.
MarshalJSONTo
Slice, Map · E L T
MarshalJSONTo implements the JSON v2 streaming interface. With a configured
*jsontext.Encoder named encoder, call err := orders.MarshalJSONTo(encoder).
Encoder options control formatting; encoding and writer errors are returned.
Lazy forms still materialize first, and T writes no collection data if source
materialization fails. For ordinary use, prefer MarshalJSON’s
json.Marshal example.
UnmarshalJSON
Slice, Map · E L T · Pointer Receiver
UnmarshalJSON is the compatibility decoding method. Prefer json.Unmarshal:
var decoded collection.Map[string, int]
err := json.Unmarshal([]byte(`{"north":8}`), &decoded)On success, decoded["north"] is 8. E follows JSON v2 merging rules, and a
decoding error can leave partial receiver updates. Lazy receivers replace their
iterator only after successful decoding, installing a replayable source over
the entire decoded container. T decoded values carry nil source errors. Lazy
decoding is not streaming input traversal.
UnmarshalJSONFrom
Slice, Map · E L T · Pointer Receiver
UnmarshalJSONFrom implements JSON v2 decoding from a *jsontext.Decoder.
Given a decoder named decoder and the eager map decoded above, call
err := decoded.UnmarshalJSONFrom(decoder). Receiver updates and failure rules
match UnmarshalJSON. Both streaming interface types come
from encoding/json/jsontext.
For exact declarations, see the collection API reference.