array

The ordered-collection composite of go-composites. An Array holds interface{} items and exposes both stack-like access and functional combinators, all returning a Result so failures (and short-circuits) are values, never panics or nil.

Install

go get github.com/go-composites/array

Access & mutation

New() returns an empty Array. Unless noted, each method returns a Result.Interface.

method	result payload	notes
Push(item)	the Array	append to the end
Pop()	the removed item	error Result on an empty Array
First()	the first item
Last()	the last item
Fetch(i)	the item at i
Insert(i, item)	the Array	shift the tail right; valid i is 0..Len() (append at Len()); out-of-range → error Result
Delete(i)	the removed item	shift the tail left; out-of-range → error Result
Reverse()	the Array	reverse in place
Clear()	completion Result	drop all elements
Copy()	a new Array	deep copy of the backing slice (independent of the receiver)

Queries

method	returns	notes
Len()	Go int	element count
IsEmpty()	Go bool	Len() == 0
Contains(item)	Result of Go bool	membership, via reflect.DeepEqual
IndexOf(item)	Result of Go int	index of the first match, or -1
Slice(start, end)	a new independent Array	elements [start:end); out-of-range → error Result
Sort(less)	the Array	stable sort in place (sort.SliceStable)

Combinators

All take a predicate/function returning Result.Interface and short-circuit on the first error Result (propagating it), mirroring Each:

method	result payload	notes
Each(fn)	completion Result	iterate; stop on first error
Map(fn)	a new Array	collect each fn payload
Filter(pred)	a new Array	keep items whose pred is truthy
Reduce(seed, fn)	final accumulator	left fold threading the accumulator
Find(pred)	first matching item	not-found → a Result carrying an error
Any(pred)	Go bool	true on first truthy item (vacuously false on empty)
All(pred)	Go bool	false on first falsy item (vacuously true on empty)

Truthiness (for Filter/Find/Any/All) accepts a Go bool, any value with an IsTrue() bool method (e.g. a Boolean.Interface, matched structurally so array need not import — and cycle with — boolean), nil (falsy), and treats any other non-nil payload as truthy.

Null-Object

Null() returns the never-nil Null-Object Array: an empty, immutable placeholder honouring the full Interface. IsNull() reports true for it and false for every concrete Array. Mutating methods are successful no-ops and queries return empty/false/zero values.

a := Array.New()
a.Push(1); a.Push(2); a.Push(3)

doubled := a.Map(func(_ int, item interface{}) Result.Interface {
    return Result.New(Result.WithPayload(item.(int) * 2))
}) // payload: Array [2 4 6]

sum := a.Reduce(0, func(acc, item interface{}) Result.Interface {
    return Result.New(Result.WithPayload(acc.(int) + item.(int)))
}) // payload: 6

Each method has a package-level twin (Array.Map(items, fn), …) operating on a raw []interface{}.

License

BSD-3-Clause © the go-composites/array authors.