import "github.com/gocanto/collection/collection"
Collection[T] is a generic wrapper around a Go slice that provides a fluent, chainable API for filtering, sorting, transforming, and aggregating data. It is the core type of the collection package.
⚠️ Note on Generics: Go generics do not allow methods to introduce new type parameters. Functions likeMap,Reduce,Pluck, andGroupByare implemented as package-level functions (e.g.,collection.Map(c, fn)), not methods.
| Function | Purpose |
|---|---|
| New | Creates a new collection from variadic arguments. |
| Collect | Creates a new collection from an existing slice. |
| Empty | Creates an empty collection of the given type. |
| Wrap | Wraps any value into a collection. |
| Unwrap | Extracts the underlying slice from a collection. |
| Times | Creates a collection by invoking a callback N times. |
| Range | Creates a collection of consecutive integers. |
| All | Returns the underlying slice. |
| Count | Returns the number of items in the collection. |
| IsEmpty | Reports whether the collection is empty. |
| IsNotEmpty | Reports whether the collection is not empty. |
| ContainsOneItem | Reports if there is exactly one item. |
| ContainsManyItems | Reports if there are multiple items. |
| Has | Reports whether a given index exists. |
| Function | Purpose |
|---|---|
| First | Returns the first item matching a predicate. |
| FirstOrFail | Returns the first item or an error if not found. |
| Last | Returns the last item matching a predicate. |
| Sole | Returns the only item matching a predicate (or error). |
| Get | Returns the item at a given index (with optional default). |
| Search | Returns the index of the first matching item. |
| Contains | Reports if any item satisfies a predicate. |
| Before | Returns the item before the first match. |
| After | Returns the item after the first match. |
| Function | Purpose |
|---|---|
| Push / Add | Appends items to the collection (mutates). |
| Prepend | Adds an item to the beginning (mutates). |
| Pop | Removes and returns the last item. |
| Shift | Removes and returns the first item. |
| Put | Sets the item at a given index. |
| Pull | Removes and returns an item by index. |
| Forget | Removes an item by index (mutates). |
| Each | Iterates over items with a callback. |
| Tap | Passes the collection to a callback for side effects. |
| Iter | Returns a Go 1.23+ iterator (iter.Seq[T]). |
| Function | Purpose |
|---|---|
| Map | Transforms items into a new type (Package-level). |
| FlatMap | Maps and flattens results (Package-level). |
| Reduce | Accumulates a single result (Package-level). |
| Filter / Where | Returns items matching a predicate. |
| Unique | Returns distinct items (Package-level). |
| Sort / SortBy | Returns a new sorted collection. |
| Reverse | Returns a reversed collection. |
| Shuffle | Returns a randomized collection. |
| Function | Purpose |
|---|---|
| Chunk | Breaks the collection into multiple slices of N size. |
| Split | Splits items into a fixed number of groups. |
| Slice | Extracts a portion of the collection. |
| Take | Returns N items from the front or back. |
| Skip | Skips N items and returns the rest. |
| ForPage | Returns a subset for a specific page. |
| Function | Purpose |
|---|---|
| Concat / Merge | Joins two datasets. |
| Zip | Merges multiple slices element-by-element. |
| Sum / Avg | Computes totals or averages (Package-level). |
| Min / Max | Finds minimum or maximum values (Package-level). |
| GroupBy | Groups items into a map of collections. |
func New[T any](items ...T) *Collection[T]Creates a new collection from variadic arguments.
func Collect[T any](items []T) *Collection[T]Creates a new collection from an existing slice.
func Empty[T any]() *Collection[T]Creates an empty collection of the given type.
func (c *Collection[T]) All() []TReturns the underlying slice.
func (c *Collection[T]) Count() intReturns the number of items in the collection.
func (c *Collection[T]) IsEmpty() bool
func (c *Collection[T]) IsNotEmpty() boolfunc (c *Collection[T]) First(predicates ...func(T, int) bool) (T, bool)Returns the first matching element.
func (c *Collection[T]) Get(index int, defaults ...T) (T, bool)Returns the item at the given index with an optional default value.
func (c *Collection[T]) Contains(predicate func(T, int) bool) boolReports whether any item satisfies the predicate.
func (c *Collection[T]) Push(values ...T) *Collection[T]Appends items to the collection. Mutates in place.
func (c *Collection[T]) Forget(index int) *Collection[T]Removes an item by index. Mutates in place.
func (c *Collection[T]) Each(callback func(T, int) bool) *Collection[T]Iterates over items. Return false to stop early.
func (c *Collection[T]) Iter() iter.Seq[T]Returns a Go 1.23+ iterator compatible with for range.
func Map[T any, R any](c *Collection[T], callback func(T, int) R) *Collection[R]Transforms each item into a new type.
func Reduce[T any, R any](c *Collection[T], callback func(R, T, int) R, initial R) RReduces the collection to a single value.
func (c *Collection[T]) Filter(callback func(T, int) bool) *Collection[T]Returns items matching the predicate.
func Unique[T any, K comparable](c *Collection[T], keyFunc func(T) K) *Collection[T]Returns a new collection with distinct keys.
func (c *Collection[T]) Sort(less func(a, b T) bool) *Collection[T]Returns a new collection sorted by the provided function.
func (c *Collection[T]) Chunk(size int) [][]TBreaks the collection into multiple slices of the given size.
func (c *Collection[T]) Take(limit int) *Collection[T]Returns N items from the front (positive) or back (negative).
func (c *Collection[T]) Merge(items []T) *Collection[T]Joins the collection with another slice.
func Sum[T Numeric](c *Collection[T]) T
func Avg[T Numeric](c *Collection[T]) float64func Min[T cmp.Ordered](c *Collection[T]) (T, bool)
func Max[T cmp.Ordered](c *Collection[T]) (T, bool)func (c *Collection[T]) ToJSON() ([]byte, error)
func (c *Collection[T]) ToPrettyJSON() ([]byte, error)