Documentation
¶
Overview ¶
Package arr holds the helpers for reading and reshaping maps and slices: dotted-key access (Get, Set, Has, Forget), subsetting (Only, Except, Where), flattening (Dot, Undot, Collapse) and query-string rendering (Query).
Two shapes ¶
Each function takes the shape it walks: map[string]any where it reads keys, and a slice where it walks a list. The doc comment on each one says which.
A key holding dots is a path. Get and Has descend through nested maps, and a numeric segment indexes into a nested slice, so one path can cross both shapes; Set creates the levels that are missing.
A map carries no order of its own, so wherever the output would otherwise depend on one -- Divide, Query, Dot over nested values, Undot -- the keys are sorted first and the result is stable across runs.
Index ¶
- Variables
- func Accessible(v any) bool
- func Add(array map[string]any, key string, v any) map[string]any
- func Array(array map[string]any, key string, def []any) ([]any, error)
- func Arrayable(v any) bool
- func Boolean(array map[string]any, key string, def *bool) (bool, error)
- func Collapse[T any](array [][]T) []T
- func CrossJoin[T any](arrays ...[]T) [][]T
- func Divide(array map[string]any) ([]string, []any)
- func Dot(array map[string]any, prepend string) map[string]any
- func Every[T any](array []T, callback func(item T, key int) bool) bool
- func Except(array map[string]any, keys ...string) map[string]any
- func ExceptValues[T comparable](array []T, values ...T) []T
- func Exists(array map[string]any, key string) bool
- func First[T any](array []T, callback func(item T, key int) bool, def T) T
- func Flatten(array []any, depth int) []any
- func Float(array map[string]any, key string, def *float64) (float64, error)
- func Forget(array map[string]any, keys ...string)
- func From(items any) (any, error)
- func Get(array map[string]any, key string, def any) any
- func Has(array map[string]any, keys ...string) bool
- func HasAll(array map[string]any, keys ...string) bool
- func HasAny(array map[string]any, keys ...string) bool
- func Integer(array map[string]any, key string, def *int) (int, error)
- func IsAssoc(v any) bool
- func IsList(v any) bool
- func Join(array []string, glue, finalGlue string) string
- func KeyBy[T any](array []T, keyBy func(T) string) map[string]T
- func Last[T any](array []T, callback func(item T, key int) bool, def T) T
- func Map[T, U any](array []T, callback func(item T, key int) U) []U
- func MapSpread[T any](array [][]any, callback func(args ...any) T) []T
- func MapWithKeys[T, V any](array []T, callback func(item T, key int) map[string]V) map[string]V
- func Only(array map[string]any, keys ...string) map[string]any
- func OnlyValues[T comparable](array []T, values ...T) []T
- func Partition[T any](array []T, callback func(item T, key int) bool) (passed, failed []T)
- func Pluck(array []any, value, key string) any
- func Prepend[T any](array []T, v T) []T
- func PrependKeysWith(array map[string]any, prependWith string) map[string]any
- func Pull(array map[string]any, key string, def any) any
- func Push(array map[string]any, key string, values ...any) (map[string]any, error)
- func Query(array map[string]any) string
- func Random[T any](array []T, number int) ([]T, error)
- func Reject[T any](array []T, callback func(item T, key int) bool) []T
- func Select(array []map[string]any, keys ...string) []map[string]any
- func Set(array map[string]any, key string, v any) map[string]any
- func Shuffle[T any](array []T) []T
- func Sole[T any](array []T, callback func(item T, key int) bool) (T, error)
- func Some[T any](array []T, callback func(item T, key int) bool) bool
- func Sort[T any](array []T, compare func(a, b T) int) []T
- func SortDesc[T any](array []T, compare func(a, b T) int) []T
- func SortRecursive(array []any, descending bool) []any
- func SortRecursiveDesc(array []any) []any
- func String(array map[string]any, key string, def *string) (string, error)
- func Take[T any](array []T, limit int) []T
- func ToCssClasses(array any) string
- func ToCssStyles(array any) string
- func Undot(array map[string]any) map[string]any
- func Where[T any](array []T, callback func(item T, key int) bool) []T
- func WhereNotNull(array []any) []any
- func Wrap(v any) []any
- type Arrayer
Constants ¶
This section is empty.
Variables ¶
var ErrItemNotFound = errors.New("arr: item not found")
ErrItemNotFound is returned by Sole when nothing in the list matched: the caller asked for exactly one item and got none. It reports the shape of the data, not a mistake in the call, so match it with errors.Is and decide what an empty result means here -- a missing record, a default, an empty page.
var ErrMultipleItemsFound = errors.New("arr: multiple items found")
ErrMultipleItemsFound is returned by Sole when more than one item matched: the caller asked for exactly one and the filter was not selective enough. Only the fact is reported, never how many matched or which -- reaching it means either the callback is too loose or the list holds a duplicate that should not be there.
Functions ¶
func Accessible ¶
Accessible reports whether the value can be indexed at all: a map, a slice or an array.
func Add ¶
Add writes the value under the dotted key only when nothing is there yet, and returns the same map.
func Array ¶
Array reads a dotted key and requires the value to be a []any, returning an error naming the key and the type found when it is not.
A nil default means no default, which fails the type check unless the key is present.
func Arrayable ¶
Arrayable reports whether the value can be turned into an array: a map, a slice, an array, an Arrayer or a json.Marshaler.
func Boolean ¶
Boolean reads a dotted key and requires the value to be a bool, returning an error naming the key and the type found when it is not.
The default is a pointer so that nil can mean no default, which fails the type check unless the key is present.
func Collapse ¶
func Collapse[T any](array [][]T) []T
Collapse returns one flat list out of a list of lists.
func CrossJoin ¶
func CrossJoin[T any](arrays ...[]T) [][]T
CrossJoin returns every combination of the given lists, one list per combination, with the last list varying fastest.
func Divide ¶
Divide returns the keys in one list and the values in another, aligned by position. The keys are sorted, because a map has no order of its own.
func Dot ¶
Dot returns a nested map flattened into one level, its keys joined with dots and carrying the given prefix. Nested lists are walked too, keyed by their index. An empty nested map or list is kept as a value, not descended into.
func Except ¶
Except returns everything but the given dotted keys. The map is copied first, so the original is left alone.
func ExceptValues ¶
func ExceptValues[T comparable](array []T, values ...T) []T
ExceptValues returns everything but the given values, compared with ==.
func First ¶
First returns the first item passing the truth test, or the default when nothing passes. A nil callback takes the first item of all.
func Flatten ¶
Flatten squashes a multi-dimensional list into one level. A depth of 1 flattens one level; a depth of zero or less flattens all the way down.
func Float ¶
Float reads a dotted key and requires the value to be a float64, returning an error naming the key and the type found when it is not. A nil default means no default.
func Forget ¶
Forget removes one or many dotted keys. A map is a reference, so this mutates in place and returns nothing.
func From ¶
From returns the underlying array of the given value. A map, a slice, an Arrayer, a json.Marshaler or a struct all convert; a scalar, and nil, are an error.
The result is map[string]any for keyed values and []any for lists, so the caller type-asserts on the shape it expects.
func Get ¶
Get reads a value by dotted key, falling back to the default. A default that is a func() any is invoked and its result returned.
The empty key returns the whole map. A numeric segment indexes into a nested []any, so one path can cross both shapes.
func Has ¶
Has reports whether every one of the dotted keys is present. An empty map, or an empty key list, is false.
func HasAll ¶
HasAll reports whether every one of the dotted keys is present, which is what Has reports under a name that says so.
func HasAny ¶
HasAny reports whether any one of the dotted keys is present. An empty map, or an empty key list, is false.
func Integer ¶
Integer reads a dotted key and requires the value to be an int, returning an error naming the key and the type found when it is not. A nil default means no default.
func Join ¶
Join returns the items joined by glue, with the last one joined by finalGlue instead when finalGlue is not empty.
func KeyBy ¶
KeyBy keys a list by the string the callback returns for each item. Two items yielding the same key leave the later one.
func Last ¶
Last returns the last item passing the truth test, or the default when nothing passes. A nil callback takes the last item of all.
func Map ¶
Map returns the callback run over every item, in order. The callback is given the item and its index.
func MapSpread ¶
MapSpread runs the callback over every nested chunk, passing the chunk's items followed by the chunk's index.
func MapWithKeys ¶
MapWithKeys merges into one map the pairs the callback returns for each item. A key returned twice leaves the later value.
func Only ¶
Only returns the subset of the map under the given exact keys. A key the map does not hold is skipped.
func OnlyValues ¶
func OnlyValues[T comparable](array []T, values ...T) []T
OnlyValues returns only the given values, compared with ==.
func Pluck ¶
Pluck reads one value out of every item by dotted path. With an empty key the result is a []any in the items' order; with a key it is a map[string]any keyed by the value found at that path.
func Prepend ¶
func Prepend[T any](array []T, v T) []T
Prepend returns a new list with the value pushed onto the front. To write into a map instead, use Set: a map has no front.
func PrependKeysWith ¶
PrependKeysWith returns a new map with every key given the prefix.
func Pull ¶
Pull reads a dotted key and removes it, returning the value or the default. A map is a reference, so the removal is seen by every holder of it.
func Push ¶
Push appends values to the list living under a dotted key and returns the same map. A key holding something other than a []any is an error.
func Query ¶
Query renders the map as an RFC 3986 query string, writing nested values as key[sub]=value and nested lists by index. A nil value is dropped.
A map has no order of its own, so the keys are sorted and the string is the same on every run.
func Random ¶
Random returns the given number of items, picked at random and without repetition. Asking for more than the list holds is an error; asking for none or fewer gives an empty list.
func Set ¶
Set writes a value under a dotted key, creating the levels that are missing, and returns the same map.
A map cannot be replaced through its own reference, so an empty key is a no-op and the map comes back unchanged. A nil map is a no-op too.
func Shuffle ¶
func Shuffle[T any](array []T) []T
Shuffle returns a shuffled copy of the list, leaving the original alone.
func Sole ¶
Sole returns the one item that matches. Nothing matching is ErrItemNotFound; more than one is ErrMultipleItemsFound. A nil callback takes the whole list.
func Sort ¶
Sort returns a sorted copy of the list, leaving the original alone. The argument is the comparison itself, and the sort is stable.
func SortRecursive ¶
SortRecursive returns the list sorted by value, with every nested list sorted too. Numbers compare as numbers and everything else by its rendering. Nested maps are left as they are: a map has no order to sort.
func SortRecursiveDesc ¶
SortRecursiveDesc returns the list sorted descending by value, with every nested list sorted too.
func String ¶
String reads a dotted key and requires the value to be a string, returning an error naming the key and the type found when it is not. A nil default means no default.
func Take ¶
Take returns the first limit items, or the last abs(limit) items when the limit is negative. The result is always a fresh slice.
func ToCssClasses ¶
ToCssClasses builds a class list out of plain classes and conditional ones.
A string element is always kept; a map[string]bool element keeps the keys whose condition is true, sorted, since a map has no order of its own. Any other element is dropped.
func ToCssStyles ¶
ToCssStyles builds a style list out of plain styles and conditional ones, every entry finished with a semicolon. The elements are read as ToCssClasses reads them.
func WhereNotNull ¶
WhereNotNull returns the items that are not nil.
Source Files