Gollection

About Gollection

Gollection is a simple library that provides a convenient set of helpers for working with collections of data. The word "Gollection" is a portmanteau of the words "go" and "collection".

What is a collection?

A collection is a container of related data such as a slice or a map. Currently, go channels are beyond the scope if this project due to their lack of flexibility.

What can Gollection do?

It can manipulate, partition, transform, and get stats about collections.

But why?

In an attempt to keep our go files small and clean.

Current Release

v1.0 (Amethyst)

Available Functions

Append	At	Average	Avg
Chunk	ChunkBy	Collapse	CollapseMap
Combine	CombineSlice	CombineMap	Contains
ContainsKey	Count	CountBy	Counts
CrossJoin	Diff	DiffAssoc	DiffKeys
DoesntContain	Duplicates	Each	Every
Except	Filter	First	FirstOr
FirstOrFail	FirstWhere	Flatten	FlattenMap
Flip	Forget	GroupBy	Has
HasAny	HasAnyKeys	HasEvery	HasOne
IndexOf	IsEmpty	Intersect	IntersectAssoc
IntersectByKeys	KeyBy	Last	LastOr
LastOrFail	LastWhere	Length	Map
Max	Mode	Min	Multiply
Nth	NthFromLast	Only	PadLeft
PadRight	Partition	Percentage	Prepend
Push	Pop	Random	Range
Reduce	ReduceWithIndex	Reject	RejectWithIndex
Replace	Reverse	ReverseMap	Select
Shuffle	Skip	SkipUntil	SkipWhile
Slice	Sort	SortAsc	SortBy
SortByAsc	SortByDesc	SortDesc	Splice
Split	SplitInto	Take	TakeUntil
TakeWhile	Union	Unique	Where
WhereBetween	WhereIn	WhereNot	WhereNotBetween
WhereNotIn	Zip

Append

gollection.Append([]int{1, 2, 3}, 4, 5, 6)
// [1, 2, 3, 4, 5, 6]

At

gollection.At([]int{1, 2, 3}, 1)
// 2, nil

Average

gollection.Average([]int{1, 2, 3})
// 2

Avg

alias for Average

Chunk

gollection.Chunk([]int{1, 2, 3, 4, 5, 6}, 3)
// [[1, 2, 3], [4, 5, 6]]

ChunkBy

gollection.ChunkBy([]int{1, 2, 3, 4, 5, 6}, func(n int) bool { return n%2 == 1 })
// [[1, 2], [3, 4], [5, 6]]

Collapse

gollection.Collapse([][]int{{1, 2}, {3, 4}, {5, 6}})
// [1, 2, 3, 4, 5, 6]

CollapseMap

gollection.CollapseMap([]map[string]int{{"a": 1, "c": 4}, {"b": 2, "a": 3}})
// {"a": 3, "b": 2, "c": 4}

Combine

gollection.Combine([]string{"a", "b"}, []int{1, 2})
// {"a": 1, "b": 2}

CombineSlice

alias for Combine

CombineMap

gollection.CombineMap(map[string]int{"a": 1}, map[string]int{"b": 2, "a": 3})
// {"a": 3, "b": 2}

Contains

gollection.Contains([]int{1, 2, 3, 4}, 4)
// true

ContainsKey

gollection.ContainsKey(map[string]int{"k": 1}, "k")
// true

Count

alias for len

CountBy

gollection.CountBy([]int{1, 2, 3, 4}, func(x int) bool { return x%2 == 0 })
// 2

Counts

gollection.Counts([]string{"a", "a", "b"})
// {"a": 2, "b": 1}

CrossJoin

gollection.CrossJoin([]int{1, 2, 3}, []string{"x", "y"})
// [[1, "x"], [1, "y"], [2, "x"], [2, "y"], [3, "x"], [3, "y"]]

Diff

gollection.Diff([]int{1, 2, 3}, []int{2})
// [1,3]

DiffAssoc

gollection.DiffAssoc(map[string]int{"a": 1, "b": 3}, map[string]int{"a": 1, "b": 2})
// {"b": 3}

DiffKeys

gollection.DiffKeys(map[string]int{"a": 1, "b": 2}, map[string]int{"b": 3})
// ["a"]

DoesntContain

gollection.DoesntContain([]int{1, 3, 4, 5}, 2)
// true

Duplicates

gollection.Duplicates([]int{1, 1, 2, 3, 3})
// [1,3]

Each

sum:= 0
gollection.Each([]int{1, 2, 3}, func(n int) { sum += n })
// sum = 6

Every

gollection.Every([]int{2, 4, 6}, func(n int) bool { return n%2 == 0 })
// true

Except

gollection.Except([]int{1, 2, 3}, func(n int) bool { return n == 2 })
// [1,3]

Filter

gollection.Filter([]int{1, 2, 3}, func(n int) bool { return n == 2 })
// [2]

First

gollection.First([]int{1, 2, 3}, func(n, i int) bool { return n > 2 })
// 3

FirstOr

gollection.FirstOr([]int{1, 2, 3}, func(n, i int) bool { return n > 3 }, 4)
// 4

FirstOrFail

gollection.FirstOrFail([]int{1, 2, 3}, func(n, i int) bool { return n > 3 })
// panic

FirstWhere

gollection.FirstWhere([]map[string]any{{"id": 1, "size": "S"}, {"id": 2, "size": "L"}}, "size", "L")
// {"id": 2, "size": "L"}

Flatten

gollection.Flatten([][]int{{1, 2, 3}, {4, 5}, {6}})
// [1,2,3,4,5,6]

FlattenMap

gollection.FlattenMap([]map[string]int{{"a": 1}, {"b": 2, "a": 3}, {"a": 5, "c": 4}})
// {"a": 5, "b": 2, "c": 4}

Flip

gollection.Flip(map[string]int{"b": 2, "a": 3})
// {2: "b", 3: "c"}

Forget

gollection.Forget(map[string]int{"a": 2, "b": 3, "c": 4}, "a", "c")
// {"b": 3}

GroupBy

gollection.GroupBy([]map[string]string{{"t": "a", "u": "1"}, {"t": "b", "u": "2"}, {"t": "a", "u": "3"}}, "t")
// {"a": [{"t": "a", "u": "1"}, {"t": "a", "u": "3"}], "b": {"t": "b", "u": "2"}}

Has

alias for Contains

HasAny

gollection.HasAny([]int{1, 2, 3}, []int{0, 3})
// true

HasAnyKeys

gollection.HasAnyKeys(map[string]int{"a": 1}, "a", "b")
// true

HasEvery

gollection.HasEvery([]int{1, 2, 3}, []int{1, 2})
// true

HasOne

gollection.HasOne([]int{1, 4, 5}, []int{1, 2, 3})
// true
gollection.HasOne([]int{1, 2, 5}, []int{1, 2, 3})
// false

IndexOf

gollection.IndexOf([]string{"a", "b", "c"}, "b")
// 1
gollection.IndexOf([]string{"a", "b", "c"}, "d")
// -1

IsEmpty

gollection.IsEmpty([]string{"a", "b", "c"})
// false

Intersect

gollection.Intersect([]int{1, 1, 2}, []int{1, 2, 2})
// [1, 2]

IntersectAssoc

gollection.IntersectAssoc(map[string]int{"a": 1, "b": 2}, map[string]int{"a": 1, "b": 9})
// {"a": 1}

IntersectByKeys

gollection.IntersectByKeys(map[string]int{"a": 1, "b": 2}, map[string]int{"b": 9})
// {"b": 2}

KeyBy

gollection.KeyBy([]map[string]int{{"k": 1}, {"k": 2, "a": 3}, {"k": 2, "b": 4}}, "k")
// {1: [{"k": 1}], 2: [{"k": 2, "a": 3}, {"k": 2, "b": 4}]}

Last

gollection.Last([]int{1, 2, 3, 4}, func(n, i int) bool { return n >= 2 })
// 4
gollection.Last([]int{1, 2, 3, 4}, func(n, i int) bool { return n > 4 })
// nil

LastOr

gollection.LastOr([]int{1, 2, 3, 4}, func(n, i int) bool { return n >= 4 }, 99)
// 4
gollection.LastOr([]int{1, 2, 3, 4}, func(n, i int) bool { return n > 4 }, 99)
// 99

LastOrFail

gollection.LastOrFail([]int{1, 2, 3, 4}, func(n, i int) bool { return n >= 4 })
// 4
gollection.LastOrFail([]int{1, 2, 3, 4}, func(n, i int) bool { return n > 4 })
// panic

LastWhere

gollection.LastWhere([]map[string]any{{"n": 1}, {"n": 2}, {"n": 2}}, "n", 2)
// {"n": 2}
gollection.LastWhere([]map[string]any{{"n": 1}, {"n": 2}, {"n": 2}}, "n", 3)
// nil

Length

alias for Count

Map

gollection.Map([]int{1, 2}, func(n int) string { return string(rune('0' + n)) })
// ["1", "2"]

Max

gollection.Max([]int{1, 3, 2, 5, 4})
// 5

Mode

gollection.Mode([]int{1, 2, 1, 2, 3, 2})
// ["1", "2"]

Min

gollection.Min([]int{3, 2, 5, 4})
// 2

Multiply

gollection.Multiply([]int{1, 2}, 3)
// [1, 1, 1, 2, 2, 2]

Nth

gollection.Nth([]string{"a", "b"}, 1)
// "b"

NthFromLast

gollection.NthFromLast([]string{"a", "b"}, 1)
// "a"

Only

gollection.Only([]map[string]int{{"a": 1, "b": 2}, {"a": 3, "b": 4, "c": 5}}, "a", "b")
// [{"a": 1, "b": 2}, {"a": 3, "b": 4}]

PadLeft

gollection.PadLeft([]int{1}, 2, 0)
// [0, 0, 1]

PadRight

gollection.PadRight([]int{1}, 4, 3)
// [1, 3, 3, 3, 3]

Partition

gollection.Partition([]int{1, 2, 3, 4}, func(i, n int) bool { return n%2 == 0 })
// [[2,4], [1,3]]
gollection.Partition([]int{1, 2, 3, 4}, func(i, n int) bool { return i < 2 })
// [[1,2], [3,4]]

Percentage

gollection.Percentage([]int{1, 2, 3, 4}, func(n int) bool { return n%2 == 0 })
// 50

Prepend

gollection.Prepend([]int{3, 4}, 1, 2)
// [1, 2, 3, 4]

Push

gollection.Push([]int{3, 4}, 1)
// [3, 4, 1]

Pop

gollection.Pop([]int{3, 4, 1})
// 1, [3, 4]

Random

gollection.Random([]int{1, 2, 3, 4, 5})
// 4, nil
gollection.Random([]int{})
// nil, Error

Range

gollection.Range([]int{0, 1, 2, 3, 4, 5}, 2, 4)
// [2, 3], nil
gollection.Range([]int{0, 1, 2, 3, 4, 5}, 4, 2)
// nil, Error

Reduce

gollection.Reduce([]int{1, 2, 3}, func(acc, n int) int { return acc + n }, 0)
// 6

ReduceWithIndex

gollection.ReduceWithIndex([]int{1, 2, 3}, func(acc, n, i int) int { return acc + i }, 0)
// 3

Reject

gollection.Reject([]int{1, 2, 3}, func(n int) bool { return n == 2 })
// [1, 3]

RejectWithIndex

gollection.RejectWithIndex([]int{1, 2, 3}, func(n, i int) bool { return i == 2 })
// [1, 2]

Replace

gollection.Replace([]int{1, 2, 3, 4, 5}, map[int]int{1: 9, 3: 10})
// [1, 9, 3, 10, 5]

Reverse

gollection.Reverse([]int{1, 2, 3, 4, 5})
// [5, 4, 3, 2, 1]

ReverseMap

gollection.ReverseMap(map[int]string{1: "x", 3: "y"})
// {"x": 1, "y": 3}

Select

gollection.Select([]map[string]any{{"a": 1, "b": "x", "c": 2.0}, {"a": 2, "b": "y", "c": 1.5}}, "a", "b")
// [{"a": 1, "b": "x"}, {"a": 2, "b": "y"}]

Shuffle

gollection.Shuffle([]int{1, 2, 3, 4, 5})
// [4, 1, 3, 5, 2]

Skip

gollection.Skip([]int{1, 1, 1, 2, 3}, 2)
// [1, 2, 3]

SkipUntil

gollection.SkipUntil([]int{1, 2, 3}, func(n int) bool { return n == 2 })
// [2, 3]

SkipWhile

gollection.SkipWhile([]int{1, 2, 1}, func(n int) bool { return n < 2 })
// [2, 1]

Slice

gollection.Slice([]int{1, 2, 3, 4, 5}, 1, 3)
// [2, 3]

Sort

gollection.Sort([]int{3, 1, 2}, gollection.SortDirectionAsc)
// [1, 2, 3]
gollection.Sort([]int{1, 3, 2}, gollection.SortDirectionDesc)
// [3, 2, 1]

SortAsc

gollection.SortAsc([]int{2, 1})
// [1, 2]

SortBy

gollection.SortBy([]map[string]int{{"v": 2}, {"v": 1}}, "v", gollection.SortDirectionAsc)
// [{"v": 1}, {"v": 2}]

SortByAsc

gollection.SortByAsc([]map[string]int{{"v": 3}, {"v": 1}}, "v")
// [{"v": 1}, {"v": 3}]

SortByDesc

gollection.SortByDesc([]map[string]int{{"v": 1}, {"v": 3}}, "v")
// [{"v": 3}, {"v": 1}]

SortDesc

gollection.SortDesc([]int{1, 3, 2})
// [3, 2, 1]

Splice

gollection.Splice([]int{1, 2, 3, 4}, 1, 2, 9, 9)
// [1, 9, 9, 4]

Split

gollection.Split([]int{1, 2, 3, 4, 5}, 2)
// [[1, 2], [3, 4], [5]]

SplitInto

gollection.SplitInto([]int{1, 2, 3, 4, 5, 6}, 2)
// [[1, 2, 3], [4, 5, 6]]

Take

gollection.Take([]int{1, 2, 3}, 2)
// [1, 2]

TakeUntil

gollection.TakeUntil([]int{1, 2, 3}, func(n int) bool { return n == 2 })
// [1]

TakeWhile

gollection.TakeWhile([]int{1, 2, 3}, func(n int) bool { return n < 3 })
// [1, 2]

Union

gollection.Union([]int{1, 2}, []int{2, 3})
// [1, 2, 3]

Unique

gollection.Unique([]int{1, 1, 2, 3, 3})
// [2]

Where

gollection.Where([]map[string]int{{"k": 1}, {"k": 2}}, "k", 2)
// [{"k": 2}]

WhereBetween

gollection.WhereBetween([]map[string]int{{"x": 2}, {"x": 5}, {"x": 10}}, "x", 2, 5)
// [{"x": 2}, {"x": 5}]

WhereIn

gollection.WhereIn([]map[string]int{{"t": 1}, {"t": 9}}, "t", []int{9})
// [{"t": 9}]

WhereNot

gollection.WhereNot([]map[string]int{{"t": 1}, {"t": 2}}, "t", 1)
// [{"t": 2}]

WhereNotBetween

gollection.WhereNotBetween([]map[string]int{{"x": 1}, {"x": 4}, {"x": 7}}, "x", 3, 6)
// [{"x": 1}, {"x": 7}]

WhereNotIn

gollection.WhereNotIn([]map[string]int{{"t": 1}, {"t": 2}}, "t", []int{1})
// [{"t": 2}]

Zip

gollection.Zip([]int{1, 2}, []string{"a", "b"})
// [[1, "a"], [2, "b"]]

Did we miss something? Create an issue or a PR.