β¨ lo
is a Lodash-style Go library based on Go 1.18+ Generics.
This project have started as an experiment to discover generics implementation. It may look like Lodash in some aspects. I used to code with the awesome go-funk package, but it uses reflection and therefore is not typesafe.
As expected, benchmarks demonstrate that generics will be much faster than implementations based on reflect stdlib package. Benchmarks also shows similar performances to pure for
loops. [#-benchmark](See below).
In the future, 5 to 10 helpers will overlap with those coming into the Go standard library (under package names slices
and maps
). Anyway I feel this library legitimate to offer many more such useful abstractions.
I wanted a short name, similar to "Lodash", and no Go package currently use this name.
go get github.com/samber/lo
You can import lo
using a basic statement:
import (
"github.com/samber/lo"
lop "github.com/samber/lo/parallel"
)
Then use one of the helpers below:
names := lo.Uniq[string]([]string{"Samuel", "Marc", "Samuel"})
// []string{"Samuel", "Marc"}
GoDoc: https://godoc.org/github.com/samber/lo
Supported helpers for slices:
- Filter
- Map
- Reduce
- ForEach
- Uniq
- UniqBy
- GroupBy
- Chunk
- Flatten
- Shuffle
- Reverse
- Fill
- ToMap
Supported helpers for maps:
- Keys
- Values
- Entries
- FromEntries
- Assign (maps merge)
Supported intersection helpers:
- Contains
- Every
- Some
- Intersect
- Difference
Supported search helpers:
- IndexOf
- LastIndexOf
- Find
- Min
- Max
- Last
- Nth
Other functional programming helpers:
- Ternary (1 line if/else statement)
- If / ElseIf / Else
- Switch / Case / Default
- ToPtr
- ToSlicePtr
Constraints:
- Clonable
Manipulates a slice and transforms it to a slice of another type:
import "github.com/samber/lo"
lo.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}
Parallel processing: like lo.Map()
, but mapper is called in goroutine. Results are returns in the same order.
import lop "github.com/samber/lo/parallel"
lop.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
return strconv.FormatInt(x, 10)
}, 2)
// []string{"1", "2", "3", "4"}
Iterates over elements of collection, returning an array of all elements predicate returns truthy for.
even := lo.Filter[int]([]int{1, 2, 3, 4}, func(x int, _ int) bool {
return x%2 == 0
})
// []int{2, 4}
Returns true if an element is present in a collection.
present := lo.Contains[int]([]int{0, 1, 2, 3, 4, 5}, 5)
// true
Reduces collection to a value which is the accumulated result of running each element in collection through accumulator, where each successive invocation is supplied the return value of the previous.
sum := lo.Reduce[int, int]([]int{1, 2, 3, 4}, func(agg int, item int, _ int) int {
return agg + item
}, 0)
// 10
Iterates over elements of collection and invokes iteratee for each element.
import "github.com/samber/lo"
lo.ForEach[string]([]string{"hello", "world"}, func(x string, _ int) {
println(x)
})
// prints "hello\nworld\n"
Parallel processing: like lo.ForEach()
, but callback is called in goroutine.
import lop "github.com/samber/lo/parallel"
lop.ForEach[string]([]string{"hello", "world"}, func(x string, _ int) {
println(x)
})
// prints "hello\nworld\n" or "world\nhello\n"
Returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array.
uniqValues := lo.Uniq[int]([]int{1, 2, 2, 1})
// []int{1, 2}
Returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array. It accepts iteratee
which is invoked for each element in array to generate the criterion by which uniqueness is computed.
uniqValues := lo.UniqBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func (i int) int {
return i%3
})
// []int{0, 1, 2}
Returns an object composed of keys generated from the results of running each element of collection through iteratee.
groups := GroupBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func (i int) int {
return i%3
})
// map[int][]int{0: []int{0, 3}, 1: []int{1, 4}, 2: []int{2, 5}}
Returns an array of elements split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.
lo.Chunk[int]([]int{0, 1, 2, 3, 4, 5}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}}
lo.Chunk[int]([]int{0, 1, 2, 3, 4, 5, 6}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}, {6}}
lo.Chunk[int]([]int{}, 2)
// [][]int{}
lo.Chunk[int]([]int{0}, 2)
// [][]int{{0}}
Returns an array a single level deep.
flat := lo.Flatten[int]([][]int{{0, 1}, {2, 3, 4, 5}})
// []int{0, 1, 2, 3, 4, 5}
Returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.
randomOrder := lo.Shuffle[int]([]int{0, 1, 2, 3, 4, 5})
// []int{0, 1, 2, 3, 4, 5}
Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
reverseOder := lo.Reverse[int]([]int{0, 1, 2, 3, 4, 5})
// []int{5, 4, 3, 2, 1, 0}
Fills elements of array with initial
value.
type foo struct {
bar string
}
func (f foo) Clone() foo {
return foo{f.bar}
}
initializedSlice := lo.Fill[foo]([]foo{foo{"a"}, foo{"a"}}, foo{"b"})
// []foo{foo{"b"}, foo{"b"}}
Transforms a slice or an array of structs to a map based on a pivot callback.
m := lo.ToMap[int, string]([]string{"a", "aa", "aaa"}, func (str string) int {
return len(str)
})
// map[int]string{1: "a", 2: "aa", 3: "aaa"}
Creates an array of the map keys.
keys := lo.Keys[string, int](map[string]int{"foo": 1, "bar": 2})
// []string{"bar", "foo"}
Creates an array of the map values.
values := lo.Values[string, int](map[string]int{"foo": 1, "bar": 2})
// []int{1, 2}
Transforms a map into array of key/value pairs.
entries := lo.Entries[string, int](map[string]int{"foo": 1, "bar": 2})
// []lo.Entry[string, int]{
// {
// Key: "foo",
// Value: 1,
// },
// {
// Key: "bar",
// Value: 2,
// },
// }
Transforms an array of key/value pairs into a map.
m := lo.FromEntries[string, int]([]lo.Entry[string, int]{
{
Key: "foo",
Value: 1,
},
{
Key: "bar",
Value: 2,
},
})
// map[string]int{"foo": 1, "bar": 2}
Merges multiple maps from left to right.
mergedMaps := lo.Assign[string, int](
map[string]int{"a": 1, "b": 2},
map[string]int{"b": 3, "c": 4},
)
// map[string]int{"a": 1, "b": 3, "c": 4}
Returns true if all elements of a subset are contained into a collection.
ok := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true
ko := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// false
Returns true if at least 1 element of a subset is contained into a collection.
ok := lo.Some[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true
ko := lo.Some[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// false
Returns the intersection between two collections.
result1 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// []int{0, 2}
result2 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 6}
// []int{0}
result3 := lo.Intersect[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// []int{}
Returns the difference between two collections.
- The first value is the collection of element absent of list2.
- The second value is the collection of element absent of list1.
left, right := lo.Difference[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2, 6})
// []int{1, 3, 4, 5}, []int{6}
left, right := Difference[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 1, 2, 3, 4, 5})
// []int{}, []int{}
Returns the index at which the first occurrence of a value is found in an array or return -1 if the value cannot be found.
found := lo.IndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 2)
// 2
notFound := lo.IndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 6)
// -1
Returns the index at which the last occurrence of a value is found in an array or return -1 if the value cannot be found.
found := lo.LastIndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 2)
// 4
notFound := lo.LastIndexOf[int]([]int{0, 1, 2, 1, 2, 3}, 6)
// -1
Search an element in a slice based on a predicate. It returns element and true if element was found.
str, ok := lo.Find[string]([]string{"a", "b", "c", "d"}, func(i string) bool {
return i == "b"
})
// "b", true
str, ok := lo.Find[string]([]string{"foobar"}, func(i string) bool {
return i == "b"
})
// "", false
Search the minimum value of a collection.
min := lo.Min[int]([]int{1, 2, 3})
// 1
min := lo.Min[int]([]int{})
// 0
Search the maximum value of a collection.
min := lo.Max[int]([]int{1, 2, 3})
// 3
min := lo.Max[int]([]int{})
// 0
Returns the last element of a collection or error if empty.
last, err := lo.Last[int]([]int{1, 2, 3})
// 3
Returns the element at index nth
of collection. If nth
is negative, the nth element from the end is returned. An error is returned when nth is out of slice bounds.
nth, err := lo.Nth[int]([]int{0, 1, 2, 3}, 2)
// 2
nth, err := lo.Nth[int]([]int{0, 1, 2, 3}, -2)
// 2
A 1 line if/else statement.
result := lo.Ternary[string](true, "a", "b")
// "a"
result := lo.Ternary[string](false, "a", "b")
// "b"
result := lo.If[int](true, 1).
ElseIf(false, 2).
Else(3)
// 1
result := lo.If[int](false, 1).
ElseIf(true, 2).
Else(3)
// 2
result := lo.If[int](false, 1).
ElseIf(false, 2).
Else(3)
// 3
result := lo.Switch[int, string](1).
Case(1, "1").
Case(2, "2").
Default("3")
// "1"
result := lo.Switch[int, string](2).
Case(1, "1").
Case(2, "2").
Default("3")
// "2"
result := lo.Switch[int, string](42).
Case(1, "1").
Case(2, "2").
Default("3")
// "3"
Using callbacks:
result := lo.Switch[int, string](1).
CaseF(1, func () string {
return "1"
}).
CaseF(2, func () string {
return "2"
}).
DefaultF(func () string {
return "3"
})
// "1"
Returns a pointer copy of value.
ptr := lo.ToPtr[string]("hello world")
// *string{"hello world"}
Returns a slice of pointer copy of value.
ptr := lo.ToSlicePtr[string]([]string{"hello", "world"})
// []*string{"hello", "world"}
We executed a simple benchmark with the a dead-simple lo.Map
loop:
See the full implementation here.
_ = lo.Map[int64](arr, func(x int64, i int) string {
return strconv.FormatInt(x, 10)
})
Result:
Here is a comparison between lo.Map
, lop.Map
, go-funk
library and a simple Go for
loop.
$ go test -benchmem -bench ./...
goos: linux
goarch: amd64
pkg: github.com/samber/lo
cpu: Intel(R) Core(TM) i5-7267U CPU @ 3.10GHz
BenchmarkMap/lo.Map-8 8 131041218 ns/op 39998055 B/op 1000001 allocs/op
BenchmarkMap/lop.Map-8 2 509805437 ns/op 120018304 B/op 3000214 allocs/op
BenchmarkMap/reflect-8 2 840512374 ns/op 170325888 B/op 4000042 allocs/op
BenchmarkMap/for-8 9 127074794 ns/op 39998040 B/op 1000001 allocs/op
PASS
ok github.com/samber/lo 7.531s
lo.Map
is way faster (x7) thango-funk
, a relection-based Map implementation.lo.Map
have the same allocation profile thanfor
.lo.Map
is 4% slower thanfor
.lop.Map
is slower thanlo.Map
because it implies more memory allocation and locks.lop.Map
will be usefull for long-running callbacks, such as i/o bound processing.for
beats other implementations for memory and CPU.
- Ping me on twitter @samuelberthe (DMs, mentions, whatever :))
- Fork the project
- Fix open issues or request new features
Don't hesitate ;)
make go1.18beta1
If your OS currently not default to Go 1.18, replace BIN=go
by BIN=go1.18beta1
in the Makefile.
docker-compose run --rm dev
# Install some dev dependencies
make tools
# Run tests
make test
# or
make watch-test
- Samuel Berthe
Give a βοΈ if this project helped you!
Copyright Β© 2022 Samuel Berthe.
This project is MIT licensed.