✨ samber/lo is a Lodash-style Go library based on Go 1.18+ Generics.
This project started as an experiment with the new generics implementation. It may look like Lodash in some aspects. I used to code with the fantastic "go-funk" package, but "go-funk" uses reflection and therefore is not typesafe.
As expected, benchmarks demonstrate that generics are much faster than implementations based on the "reflect" package. Benchmarks also show similar performance gains compared to pure for loops. 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). I feel this library is legitimate and offers many more valuable abstractions.
See also:
- samber/do: A dependency injection toolkit based on Go 1.18+ Generics
- samber/mo: Monads based on Go 1.18+ Generics (Option, Result, Either...)
Why this name?
I wanted a short name, similar to "Lodash" and no Go package currently uses this name.
go get github.com/samber/lo@v1This library is v1 and follows SemVer strictly.
No breaking changes will be made to exported APIs before v2.0.0.
This library has no dependencies outside the Go standard library.
You can import lo using:
import (
"github.com/samber/lo"
lop "github.com/samber/lo/parallel"
)Then use one of the helpers below:
names := lo.Uniq[string]([]string{"Samuel", "John", "Samuel"})
// []string{"Samuel", "John"}Most of the time, the compiler will be able to infer the type so that you can call: lo.Uniq([]string{...}).
I cannot recommend it, but in case you are too lazy for repeating lo. everywhere, you can import the entire library into the namespace.
import (
. "github.com/samber/lo"
)I take no responsibility on this junk. 😁 💩
GoDoc: https://godoc.org/github.com/samber/lo
Supported helpers for slices:
- Filter
- Map
- FilterMap
- FlatMap
- Reduce
- ReduceRight
- ForEach
- Times
- Uniq
- UniqBy
- GroupBy
- Chunk
- PartitionBy
- Flatten
- Interleave
- Shuffle
- Reverse
- Fill
- Repeat
- RepeatBy
- KeyBy
- Associate / SliceToMap
- Drop
- DropRight
- DropWhile
- DropRightWhile
- Reject
- Count
- CountBy
- CountValues
- CountValuesBy
- Subset
- Slice
- Replace
- ReplaceAll
- Compact
- IsSorted
- IsSortedByKey
Supported helpers for maps:
- Keys
- ValueOr
- Values
- PickBy
- PickByKeys
- PickByValues
- OmitBy
- OmitByKeys
- OmitByValues
- Entries / ToPairs
- FromEntries / FromPairs
- Invert
- Assign (merge of maps)
- MapKeys
- MapValues
- MapEntries
- MapToSlice
Supported math helpers:
Supported helpers for strings:
Supported helpers for tuples:
Supported helpers for channels:
Supported intersection helpers:
- Contains
- ContainsBy
- Every
- EveryBy
- Some
- SomeBy
- None
- NoneBy
- Intersect
- Difference
- Union
- Without
- WithoutEmpty
Supported search helpers:
- IndexOf
- LastIndexOf
- Find
- FindIndexOf
- FindLastIndexOf
- FindOrElse
- FindKey
- FindKeyBy
- FindUniques
- FindUniquesBy
- FindDuplicates
- FindDuplicatesBy
- Min
- MinBy
- Max
- MaxBy
- Last
- Nth
- Sample
- Samples
Conditional helpers:
Type manipulation helpers:
- IsNil
- ToPtr
- EmptyableToPtr
- FromPtr
- FromPtrOr
- ToSlicePtr
- ToAnySlice
- FromAnySlice
- Empty
- IsEmpty
- IsNotEmpty
- Coalesce
Function helpers:
Concurrency helpers:
- Attempt
- AttemptWhile
- AttemptWithDelay
- AttemptWhileWithDelay
- Debounce
- DebounceBy
- Synchronize
- Async
- Transaction
Error handling:
- Validate
- Must
- Try
- Try1 -> Try6
- TryOr
- TryOr1 -> TryOr6
- TryCatch
- TryWithErrorValue
- TryCatchWithErrorValue
- ErrorsAs
Constraints:
- Clonable
Iterates over a collection and returns an array of all the elements the predicate function returns true for.
even := lo.Filter([]int{1, 2, 3, 4}, func(x int, index int) bool {
return x%2 == 0
})
// []int{2, 4}[play]
Manipulates a slice of one type and transforms it into a slice of another type:
import "github.com/samber/lo"
lo.Map([]int64{1, 2, 3, 4}, func(x int64, index int) string {
return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}[play]
Parallel processing: like lo.Map(), but the mapper function is called in a goroutine. Results are returned in the same order.
import lop "github.com/samber/lo/parallel"
lop.Map([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}Returns a slice which obtained after both filtering and mapping using the given callback function.
The callback function should return two values: the result of the mapping operation and whether the result element should be included or not.
matching := lo.FilterMap([]string{"cpu", "gpu", "mouse", "keyboard"}, func(x string, _ int) (string, bool) {
if strings.HasSuffix(x, "pu") {
return "xpu", true
}
return "", false
})
// []string{"xpu", "xpu"}[play]
Manipulates a slice and transforms and flattens it to a slice of another type. The transform function can either return a slice or a nil, and in the nil case no value is added to the final slice.
lo.FlatMap([]int{0, 1, 2}, func(x int, _ int) []string {
return []string{
strconv.FormatInt(x, 10),
strconv.FormatInt(x, 10),
}
})
// []string{"0", "0", "1", "1", "2", "2"}[play]
Reduces a collection to a single value. The value is calculated by accumulating the result of running each element in the collection through an accumulator function. Each successive invocation is supplied with the return value returned by the previous call.
sum := lo.Reduce([]int{1, 2, 3, 4}, func(agg int, item int, _ int) int {
return agg + item
}, 0)
// 10[play]
Like lo.Reduce except that it iterates over elements of collection from right to left.
result := lo.ReduceRight([][]int{{0, 1}, {2, 3}, {4, 5}}, func(agg []int, item []int, _ int) []int {
return append(agg, item...)
}, []int{})
// []int{4, 5, 2, 3, 0, 1}[play]
Iterates over elements of a collection and invokes the function over each element.
import "github.com/samber/lo"
lo.ForEach([]string{"hello", "world"}, func(x string, _ int) {
println(x)
})
// prints "hello\nworld\n"[play]
Parallel processing: like lo.ForEach(), but the callback is called as a goroutine.
import lop "github.com/samber/lo/parallel"
lop.ForEach([]string{"hello", "world"}, func(x string, _ int) {
println(x)
})
// prints "hello\nworld\n" or "world\nhello\n"Times invokes the iteratee n times, returning an array of the results of each invocation. The iteratee is invoked with index as argument.
import "github.com/samber/lo"
lo.Times(3, func(i int) string {
return strconv.FormatInt(int64(i), 10)
})
// []string{"0", "1", "2"}[play]
Parallel processing: like lo.Times(), but callback is called in goroutine.
import lop "github.com/samber/lo/parallel"
lop.Times(3, func(i int) string {
return strconv.FormatInt(int64(i), 10)
})
// []string{"0", "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.
uniqValues := lo.Uniq([]int{1, 2, 2, 1})
// []int{1, 2}[play]
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{0, 1, 2, 3, 4, 5}, func(i int) int {
return i%3
})
// []int{0, 1, 2}[play]
Returns an object composed of keys generated from the results of running each element of collection through iteratee.
import lo "github.com/samber/lo"
groups := lo.GroupBy([]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}}[play]
Parallel processing: like lo.GroupBy(), but callback is called in goroutine.
import lop "github.com/samber/lo/parallel"
lop.GroupBy([]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{0, 1, 2, 3, 4, 5}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}}
lo.Chunk([]int{0, 1, 2, 3, 4, 5, 6}, 2)
// [][]int{{0, 1}, {2, 3}, {4, 5}, {6}}
lo.Chunk([]int{}, 2)
// [][]int{}
lo.Chunk([]int{0}, 2)
// [][]int{{0}}[play]
Returns an array of elements split into groups. The order of grouped values is determined by the order they occur in collection. The grouping is generated from the results of running each element of collection through iteratee.
import lo "github.com/samber/lo"
partitions := lo.PartitionBy([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
if x < 0 {
return "negative"
} else if x%2 == 0 {
return "even"
}
return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}[play]
Parallel processing: like lo.PartitionBy(), but callback is called in goroutine. Results are returned in the same order.
import lop "github.com/samber/lo/parallel"
partitions := lop.PartitionBy([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
if x < 0 {
return "negative"
} else if x%2 == 0 {
return "even"
}
return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}Returns an array a single level deep.
flat := lo.Flatten([][]int{{0, 1}, {2, 3, 4, 5}})
// []int{0, 1, 2, 3, 4, 5}[play]
Round-robin alternating input slices and sequentially appending value at index into result.
interleaved := lo.Interleave([]int{1, 4, 7}, []int{2, 5, 8}, []int{3, 6, 9})
// []int{1, 2, 3, 4, 5, 6, 7, 8, 9}
interleaved := lo.Interleave([]int{1}, []int{2, 5, 8}, []int{3, 6}, []int{4, 7, 9, 10})
// []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}[play]
Returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.
randomOrder := lo.Shuffle([]int{0, 1, 2, 3, 4, 5})
// []int{1, 4, 0, 3, 5, 2}[play]
Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
v2.0.0. See #160.
reverseOrder := lo.Reverse([]int{0, 1, 2, 3, 4, 5})
// []int{5, 4, 3, 2, 1, 0}[play]
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{"a"}, foo{"a"}}, foo{"b"})
// []foo{foo{"b"}, foo{"b"}}[play]
Builds a slice with N copies of initial value.
type foo struct {
bar string
}
func (f foo) Clone() foo {
return foo{f.bar}
}
slice := lo.Repeat(2, foo{"a"})
// []foo{foo{"a"}, foo{"a"}}[play]
Builds a slice with values returned by N calls of callback.
slice := lo.RepeatBy(0, func (i int) string {
return strconv.FormatInt(int64(math.Pow(float64(i), 2)), 10)
})
// []string{}
slice := lo.RepeatBy(5, func(i int) string {
return strconv.FormatInt(int64(math.Pow(float64(i), 2)), 10)
})
// []string{"0", "1", "4", "9", "16"}[play]
Transforms a slice or an array of structs to a map based on a pivot callback.
m := lo.KeyBy([]string{"a", "aa", "aaa"}, func(str string) int {
return len(str)
})
// map[int]string{1: "a", 2: "aa", 3: "aaa"}
type Character struct {
dir string
code int
}
characters := []Character{
{dir: "left", code: 97},
{dir: "right", code: 100},
}
result := lo.KeyBy(characters, func(char Character) string {
return string(rune(char.code))
})
//map[a:{dir:left code:97} d:{dir:right code:100}][play]
Returns a map containing key-value pairs provided by transform function applied to elements of the given slice. If any of two pairs would have the same key the last one gets added to the map.
The order of keys in returned map is not specified and is not guaranteed to be the same from the original array.
in := []*foo{{baz: "apple", bar: 1}, {baz: "banana", bar: 2}}
aMap := lo.Associate(in, func (f *foo) (string, int) {
return f.baz, f.bar
})
// map[string][int]{ "apple":1, "banana":2 }[play]
Drops n elements from the beginning of a slice or array.
l := lo.Drop([]int{0, 1, 2, 3, 4, 5}, 2)
// []int{2, 3, 4, 5}[play]
Drops n elements from the end of a slice or array.
l := lo.DropRight([]int{0, 1, 2, 3, 4, 5}, 2)
// []int{0, 1, 2, 3}[play]
Drop elements from the beginning of a slice or array while the predicate returns true.
l := lo.DropWhile([]string{"a", "aa", "aaa", "aa", "aa"}, func(val string) bool {
return len(val) <= 2
})
// []string{"aaa", "aa", "aa"}[play]
Drop elements from the end of a slice or array while the predicate returns true.
l := lo.DropRightWhile([]string{"a", "aa", "aaa", "aa", "aa"}, func(val string) bool {
return len(val) <= 2
})
// []string{"a", "aa", "aaa"}[play]
The opposite of Filter, this method returns the elements of collection that predicate does not return truthy for.
odd := lo.Reject([]int{1, 2, 3, 4}, func(x int, _ int) bool {
return x%2 == 0
})
// []int{1, 3}[play]
Counts the number of elements in the collection that compare equal to value.
count := lo.Count([]int{1, 5, 1}, 1)
// 2[play]
Counts the number of elements in the collection for which predicate is true.
count := lo.CountBy([]int{1, 5, 1}, func(i int) bool {
return i < 4
})
// 2[play]
Counts the number of each element in the collection.
lo.CountValues([]int{})
// map[int]int{}
lo.CountValues([]int{1, 2})
// map[int]int{1: 1, 2: 1}
lo.CountValues([]int{1, 2, 2})
// map[int]int{1: 1, 2: 2}
lo.CountValues([]string{"foo", "bar", ""})
// map[string]int{"": 1, "foo": 1, "bar": 1}
lo.CountValues([]string{"foo", "bar", "bar"})
// map[string]int{"foo": 1, "bar": 2}[play]
Counts the number of each element in the collection. It ss equivalent to chaining lo.Map and lo.CountValues.
isEven := func(v int) bool {
return v%2==0
}
lo.CountValuesBy([]int{}, isEven)
// map[bool]int{}
lo.CountValuesBy([]int{1, 2}, isEven)
// map[bool]int{false: 1, true: 1}
lo.CountValuesBy([]int{1, 2, 2}, isEven)
// map[bool]int{false: 1, true: 2}
length := func(v string) int {
return len(v)
}
lo.CountValuesBy([]string{"foo", "bar", ""}, length)
// map[int]int{0: 1, 3: 2}
lo.CountValuesBy([]string{"foo", "bar", "bar"}, length)
// map[int]int{3: 3}[play]
Returns a copy of a slice from offset up to length elements. Like slice[start:start+length], but does not panic on overflow.
in := []int{0, 1, 2, 3, 4}
sub := lo.Subset(in, 2, 3)
// []int{2, 3, 4}
sub := lo.Subset(in, -4, 3)
// []int{1, 2, 3}
sub := lo.Subset(in, -2, math.MaxUint)
// []int{3, 4}[play]
Returns a copy of a slice from start up to, but not including end. Like slice[start:end], but does not panic on overflow.
in := []int{0, 1, 2, 3, 4}
slice := lo.Slice(in, 0, 5)
// []int{0, 1, 2, 3, 4}
slice := lo.Slice(in, 2, 3)
// []int{2}
slice := lo.Slice(in, 2, 6)
// []int{2, 3, 4}
slice := lo.Slice(in, 4, 3)
// []int{}[play]
Returns a copy of the slice with the first n non-overlapping instances of old replaced by new.
in := []int{0, 1, 0, 1, 2, 3, 0}
slice := lo.Replace(in, 0, 42, 1)
// []int{42, 1, 0, 1, 2, 3, 0}
slice := lo.Replace(in, -1, 42, 1)
// []int{0, 1, 0, 1, 2, 3, 0}
slice := lo.Replace(in, 0, 42, 2)
// []int{42, 1, 42, 1, 2, 3, 0}
slice := lo.Replace(in, 0, 42, -1)
// []int{42, 1, 42, 1, 2, 3, 42}[play]
Returns a copy of the slice with all non-overlapping instances of old replaced by new.
in := []int{0, 1, 0, 1, 2, 3, 0}
slice := lo.ReplaceAll(in, 0, 42)
// []int{42, 1, 42, 1, 2, 3, 42}
slice := lo.ReplaceAll(in, -1, 42)
// []int{0, 1, 0, 1, 2, 3, 0}[play]
Returns a slice of all non-zero elements.
in := []string{"", "foo", "", "bar", ""}
slice := lo.Compact[string](in)
// []string{"foo", "bar"}[play]
Checks if a slice is sorted.
slice := lo.IsSorted([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
// true[play]
Checks if a slice is sorted by iteratee.
slice := lo.IsSortedByKey([]string{"a", "bb", "ccc"}, func(s string) int {
return len(s)
})
// true[play]
Creates an array of the map keys.
keys := lo.Keys[string, int](map[string]int{"foo": 1, "bar": 2})
// []string{"foo", "bar"}[play]
Creates an array of the map values.
values := lo.Values[string, int](map[string]int{"foo": 1, "bar": 2})
// []int{1, 2}[play]
Returns the value of the given key or the fallback value if the key is not present.
value := lo.ValueOr[string, int](map[string]int{"foo": 1, "bar": 2}, "foo", 42)
// 1
value := lo.ValueOr[string, int](map[string]int{"foo": 1, "bar": 2}, "baz", 42)
// 42[play]
Returns same map type filtered by given predicate.
m := lo.PickBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(key string, value int) bool {
return value%2 == 1
})
// map[string]int{"foo": 1, "baz": 3}[play]
Returns same map type filtered by given keys.
m := lo.PickByKeys(map[string]int{"foo": 1, "bar": 2, "baz": 3}, []string{"foo", "baz"})
// map[string]int{"foo": 1, "baz": 3}[play]
Returns same map type filtered by given values.
m := lo.PickByValues(map[string]int{"foo": 1, "bar": 2, "baz": 3}, []int{1, 3})
// map[string]int{"foo": 1, "baz": 3}[play]
Returns same map type filtered by given predicate.
m := lo.OmitBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(key string, value int) bool {
return value%2 == 1
})
// map[string]int{"bar": 2}[play]
Returns same map type filtered by given keys.
m := lo.OmitByKeys(map[string]int{"foo": 1, "bar": 2, "baz": 3}, []string{"foo", "baz"})
// map[string]int{"bar": 2}[play]
Returns same map type filtered by given values.
m := lo.OmitByValues(map[string]int{"foo": 1, "bar": 2, "baz": 3}, []int{1, 3})
// map[string]int{"bar": 2}[play]
Transforms a map into array of key/value pairs.
entries := lo.Entries(map[string]int{"foo": 1, "bar": 2})
// []lo.Entry[string, int]{
// {
// Key: "foo",
// Value: 1,
// },
// {
// Key: "bar",
// Value: 2,
// },
// }[play]
Transforms an array of key/value pairs into a map.
m := lo.FromEntries([]lo.Entry[string, int]{
{
Key: "foo",
Value: 1,
},
{
Key: "bar",
Value: 2,
},
})
// map[string]int{"foo": 1, "bar": 2}[play]
Creates a map composed of the inverted keys and values. If map contains duplicate values, subsequent values overwrite property assignments of previous values.
m1 := lo.Invert(map[string]int{"a": 1, "b": 2})
// map[int]string{1: "a", 2: "b"}
m2 := lo.Invert(map[string]int{"a": 1, "b": 2, "c": 1})
// map[int]string{1: "c", 2: "b"}[play]
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}[play]
Manipulates a map keys and transforms it to a map of another type.
m2 := lo.MapKeys(map[int]int{1: 1, 2: 2, 3: 3, 4: 4}, func(_ int, v int) string {
return strconv.FormatInt(int64(v), 10)
})
// map[string]int{"1": 1, "2": 2, "3": 3, "4": 4}[play]
Manipulates a map values and transforms it to a map of another type.
m1 := map[int]int64{1: 1, 2: 2, 3: 3}
m2 := lo.MapValues(m1, func(x int64, _ int) string {
return strconv.FormatInt(x, 10)
})
// map[int]string{1: "1", 2: "2", 3: "3"}[play]
Manipulates a map entries and transforms it to a map of another type.
in := map[string]int{"foo": 1, "bar": 2}
out := lo.MapEntries(in, func(k string, v int) (int, string) {
return v,k
})
// map[int]string{1: "foo", 2: "bar"}[play]
Transforms a map into a slice based on specific iteratee.
m := map[int]int64{1: 4, 2: 5, 3: 6}
s := lo.MapToSlice(m, func(k int, v int64) string {
return fmt.Sprintf("%d_%d", k, v)
})
// []string{"1_4", "2_5", "3_6"}[play]
Creates an array of numbers (positive and/or negative) progressing from start up to, but not including end.
result := lo.Range(4)
// [0, 1, 2, 3]
result := lo.Range(-4)
// [0, -1, -2, -3]
result := lo.RangeFrom(1, 5)
// [1, 2, 3, 4, 5]
result := lo.RangeFrom[float64](1.0, 5)
// [1.0, 2.0, 3.0, 4.0, 5.0]
result := lo.RangeWithSteps(0, 20, 5)
// [0, 5, 10, 15]
result := lo.RangeWithSteps[float32](-1.0, -4.0, -1.0)
// [-1.0, -2.0, -3.0]
result := lo.RangeWithSteps(1, 4, -1)
// []
result := lo.Range(0)
// [][play]
Clamps number within the inclusive lower and upper bounds.
r1 := lo.Clamp(0, -10, 10)
// 0
r2 := lo.Clamp(-42, -10, 10)
// -10
r3 := lo.Clamp(42, -10, 10)
// 10[play]
Sums the values in a collection.
If collection is empty 0 is returned.
list := []int{1, 2, 3, 4, 5}
sum := lo.Sum(list)
// 15[play]
Summarizes the values in a collection using the given return value from the iteration function.
If collection is empty 0 is returned.
strings := []string{"foo", "bar"}
sum := lo.SumBy(strings, func(item string) int {
return len(item)
})
// 6[play]
Returns a random string of the specified length and made of the specified charset.
str := lo.RandomString(5, lo.LettersCharset)
// example: "eIGbt"[play]
Return part of a string.
sub := lo.Substring("hello", 2, 3)
// "llo"
sub := lo.Substring("hello", -4, 3)
// "ell"
sub := lo.Substring("hello", -2, math.MaxUint)
// "lo"[play]
Returns an array of strings split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.
lo.ChunkString("123456", 2)
// []string{"12", "34", "56"}
lo.ChunkString("1234567", 2)
// []string{"12", "34", "56", "7"}
lo.ChunkString("", 2)
// []string{""}
lo.ChunkString("1", 2)
// []string{"1"}[play]
An alias to utf8.RuneCountInString which returns the number of runes in string.
sub := lo.RuneLength("hellô")
// 5
sub := len("hellô")
// 6[play]
Creates a tuple from a list of values.
tuple1 := lo.T2("x", 1)
// Tuple2[string, int]{A: "x", B: 1}
func example() (string, int) { return "y", 2 }
tuple2 := lo.T2(example())
// Tuple2[string, int]{A: "y", B: 2}[play]
Returns values contained in tuple.
r1, r2 := lo.Unpack2(lo.Tuple2[string, int]{"a", 1})
// "a", 1Unpack is also available as a method of TupleX.
tuple2 := lo.T2("a", 1)
a, b := tuple2.Unpack()
// "a" 1[play]
Zip creates a slice of grouped elements, the first of which contains the first elements of the given arrays, the second of which contains the second elements of the given arrays, and so on.
When collections have different size, the Tuple attributes are filled with zero value.
tuples := lo.Zip2([]string{"a", "b"}, []int{1, 2})
// []Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}}[play]
Unzip accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.
a, b := lo.Unzip2([]Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}})
// []string{"a", "b"}
// []int{1, 2}[play]
Distributes messages from input channels into N child channels. Close events are propagated to children.
Underlying channels can have a fixed buffer capacity or be unbuffered when cap is 0.
ch := make(chan int, 42)
for i := 0; i <= 10; i++ {
ch <- i
}
children := lo.ChannelDispatcher(ch, 5, 10, DispatchingStrategyRoundRobin[int])
// []<-chan int{...}
consumer := func(c <-chan int) {
for {
msg, ok := <-c
if !ok {
println("closed")
break
}
println(msg)
}
}
for i := range children {
go consumer(children[i])
}Many distributions strategies are available:
- lo.DispatchingStrategyRoundRobin: Distributes messages in a rotating sequential manner.
- lo.DispatchingStrategyRandom: Distributes messages in a random manner.
- lo.DispatchingStrategyWeightedRandom: Distributes messages in a weighted manner.
- lo.DispatchingStrategyFirst: Distributes messages in the first non-full channel.
- lo.DispatchingStrategyLeast: Distributes messages in the emptiest channel.
- lo.DispatchingStrategyMost: Distributes to the fullest channel.
Some strategies bring fallback, in order to favor non-blocking behaviors. See implementations.
For custom strategies, just implement the lo.DispatchingStrategy prototype:
type DispatchingStrategy[T any] func(message T, messageIndex uint64, channels []<-chan T) intEg:
type Message struct {
TenantID uuid.UUID
}
func hash(id uuid.UUID) int {
h := fnv.New32a()
h.Write([]byte(id.String()))
return int(h.Sum32())
}
// Routes messages per TenantID.
customStrategy := func(message string, messageIndex uint64, channels []<-chan string) int {
destination := hash(message) % len(channels)
// check if channel is full
if len(channels[destination]) < cap(channels[destination]) {
return destination
}
// fallback when child channel is full
return utils.DispatchingStrategyRoundRobin(message, uint64(destination), channels)
}
children := lo.ChannelDispatcher(ch, 5, 10, customStrategy)
...Returns a read-only channels of collection elements. Channel is closed after last element. Channel capacity can be customized.
list := []int{1, 2, 3, 4, 5}
for v := range lo.SliceToChannel(2, list) {
println(v)
}
// prints 1, then 2, then 3, then 4, then 5Returns a slice built from channels items. Blocks until channel closes.
list := []int{1, 2, 3, 4, 5}
ch := lo.SliceToChannel(2, list)
items := ChannelToSlice(ch)
// []int{1, 2, 3, 4, 5}Implements the generator design pattern. Channel is closed after last element. Channel capacity can be customized.
generator := func(yield func(int)) {
yield(1)
yield(2)
yield(3)
}
for v := range lo.Generator(2, generator) {
println(v)
}
// prints 1, then 2, then 3Creates a slice of n elements from a channel. Returns the slice, the slice length, the read time and the channel status (opened/closed).
ch := lo.SliceToChannel(2, []int{1, 2, 3, 4, 5})
items1, length1, duration1, ok1 := lo.Buffer(ch, 3)
// []int{1, 2, 3}, 3, 0s, true
items2, length2, duration2, ok2 := lo.Buffer(ch, 3)
// []int{4, 5}, 2, 0s, falseExample: RabbitMQ consumer 👇
ch := readFromQueue()
for {
// read 1k items
items, length, _, ok := lo.Buffer(ch, 1000)
// do batching stuff
if !ok {
break
}
}Creates a slice of n elements from a channel, with timeout. Returns the slice, the slice length, the read time and the channel status (opened/closed).
generator := func(yield func(int)) {
for i := 0; i < 5; i++ {
yield(i)
time.Sleep(35*time.Millisecond)
}
}
ch := lo.Generator(0, generator)
items1, length1, duration1, ok1 := lo.BufferWithTimeout(ch, 3, 100*time.Millisecond)
// []int{1, 2}, 2, 100ms, true
items2, length2, duration2, ok2 := lo.BufferWithTimeout(ch, 3, 100*time.Millisecond)
// []int{3, 4, 5}, 3, 75ms, true
items3, length3, duration2, ok3 := lo.BufferWithTimeout(ch, 3, 100*time.Millisecond)
// []int{}, 0, 10ms, falseExample: RabbitMQ consumer 👇
ch := readFromQueue()
for {
// read 1k items
// wait up to 1 second
items, length, _, ok := lo.BufferWithTimeout(ch, 1000, 1*time.Second)
// do batching stuff
if !ok {
break
}
}Example: Multithreaded RabbitMQ consumer 👇
ch := readFromQueue()
// 5 workers
// prefetch 1k messages per worker
children := lo.ChannelDispatcher(ch, 5, 1000, lo.DispatchingStrategyFirst[int])
consumer := func(c <-chan int) {
for {
// read 1k items
// wait up to 1 second
items, length, _, ok := lo.BufferWithTimeout(ch, 1000, 1*time.Second)
// do batching stuff
if !ok {
break
}
}
}
for i := range children {
go consumer(children[i])
}Merge messages from multiple input channels into a single buffered channel. Output messages has no priority. When all upstream channels reach EOF, downstream channel closes.
stream1 := make(chan int, 42)
stream2 := make(chan int, 42)
stream3 := make(chan int, 42)
all := lo.FanIn(100, stream1, stream2, stream3)
// <-chan intBroadcasts all the upstream messages to multiple downstream channels. When upstream channel reach EOF, downstream channels close. If any downstream channels is full, broadcasting is paused.
stream := make(chan int, 42)
all := lo.FanOut(5, 100, stream)
// [5]<-chan intReturns true if an element is present in a collection.
present := lo.Contains([]int{0, 1, 2, 3, 4, 5}, 5)
// trueReturns true if the predicate function returns true.
present := lo.ContainsBy([]int{0, 1, 2, 3, 4, 5}, func(x int) bool {
return x == 3
})
// trueReturns true if all elements of a subset are contained into a collection or if the subset is empty.
ok := lo.Every([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true
ok := lo.Every([]int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// falseReturns true if the predicate returns true for all of the elements in the collection or if the collection is empty.
b := EveryBy([]int{1, 2, 3, 4}, func(x int) bool {
return x < 5
})
// trueReturns true if at least 1 element of a subset is contained into a collection. If the subset is empty Some returns false.
ok := lo.Some([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true
ok := lo.Some([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// falseReturns true if the predicate returns true for any of the elements in the collection. If the collection is empty SomeBy returns false.
b := SomeBy([]int{1, 2, 3, 4}, func(x int) bool {
return x < 3
})
// trueReturns true if no element of a subset are contained into a collection or if the subset is empty.
b := None([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// false
b := None([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// trueReturns true if the predicate returns true for none of the elements in the collection or if the collection is empty.
b := NoneBy([]int{1, 2, 3, 4}, func(x int) bool {
return x < 0
})
// trueReturns the intersection between two collections.
result1 := lo.Intersect([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// []int{0, 2}
result2 := lo.Intersect([]int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// []int{0}
result3 := lo.Intersect([]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{0, 1, 2, 3, 4, 5}, []int{0, 2, 6})
// []int{1, 3, 4, 5}, []int{6}
left, right := lo.Difference([]int{0, 1, 2, 3, 4, 5}, []int{0, 1, 2, 3, 4, 5})
// []int{}, []int{}Returns all distinct elements from given collections. Result will not change the order of elements relatively.
union := lo.Union([]int{0, 1, 2, 3, 4, 5}, []int{0, 2}, []int{0, 10})
// []int{0, 1, 2, 3, 4, 5, 10}Returns slice excluding all given values.
subset := lo.Without([]int{0, 2, 10}, 2)
// []int{0, 10}
subset := lo.Without([]int{0, 2, 10}, 0, 1, 2, 3, 4, 5)
// []int{10}Returns slice excluding empty values.
subset := lo.WithoutEmpty([]int{0, 2, 10})
// []int{2, 10}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{0, 1, 2, 1, 2, 3}, 2)
// 2
notFound := lo.IndexOf([]int{0, 1, 2, 1, 2, 3}, 6)
// -1Returns 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{0, 1, 2, 1, 2, 3}, 2)
// 4
notFound := lo.LastIndexOf([]int{0, 1, 2, 1, 2, 3}, 6)
// -1Search an element in a slice based on a predicate. It returns element and true if element was found.
str, ok := lo.Find([]string{"a", "b", "c", "d"}, func(i string) bool {
return i == "b"
})
// "b", true
str, ok := lo.Find([]string{"foobar"}, func(i string) bool {
return i == "b"
})
// "", falseFindIndexOf searches an element in a slice based on a predicate and returns the index and true. It returns -1 and false if the element is not found.
str, index, ok := lo.FindIndexOf([]string{"a", "b", "a", "b"}, func(i string) bool {
return i == "b"
})
// "b", 1, true
str, index, ok := lo.FindIndexOf([]string{"foobar"}, func(i string) bool {
return i == "b"
})
// "", -1, falseFindLastIndexOf searches an element in a slice based on a predicate and returns the index and true. It returns -1 and false if the element is not found.
str, index, ok := lo.FindLastIndexOf([]string{"a", "b", "a", "b"}, func(i string) bool {
return i == "b"
})
// "b", 4, true
str, index, ok := lo.FindLastIndexOf([]string{"foobar"}, func(i string) bool {
return i == "b"
})
// "", -1, falseSearch an element in a slice based on a predicate. It returns the element if found or a given fallback value otherwise.
str := lo.FindOrElse([]string{"a", "b", "c", "d"}, "x", func(i string) bool {
return i == "b"
})
// "b"
str := lo.FindOrElse([]string{"foobar"}, "x", func(i string) bool {
return i == "b"
})
// "x"Returns the key of the first value matching.
result1, ok1 := lo.FindKey(map[string]int{"foo": 1, "bar": 2, "baz": 3}, 2)
// "bar", true
result2, ok2 := lo.FindKey(map[string]int{"foo": 1, "bar": 2, "baz": 3}, 42)
// "", false
type test struct {
foobar string
}
result3, ok3 := lo.FindKey(map[string]test{"foo": test{"foo"}, "bar": test{"bar"}, "baz": test{"baz"}}, test{"foo"})
// "foo", trueReturns the key of the first element predicate returns truthy for.
result1, ok1 := lo.FindKeyBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(k string, v int) bool {
return k == "foo"
})
// "foo", true
result2, ok2 := lo.FindKeyBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(k string, v int) bool {
return false
})
// "", falseReturns a slice with all the unique elements of the collection. The order of result values is determined by the order they occur in the array.
uniqueValues := lo.FindUniques([]int{1, 2, 2, 1, 2, 3})
// []int{3}Returns a slice with all the unique elements of the collection. 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.
uniqueValues := lo.FindUniquesBy([]int{3, 4, 5, 6, 7}, func(i int) int {
return i%3
})
// []int{5}Returns a slice with the first occurrence of each duplicated elements of the collection. The order of result values is determined by the order they occur in the array.
duplicatedValues := lo.FindDuplicates([]int{1, 2, 2, 1, 2, 3})
// []int{1, 2}Returns a slice with the first occurrence of each duplicated elements of the collection. 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.
duplicatedValues := lo.FindDuplicatesBy([]int{3, 4, 5, 6, 7}, func(i int) int {
return i%3
})
// []int{3, 4}Search the minimum value of a collection.
Returns zero value when collection is empty.
min := lo.Min([]int{1, 2, 3})
// 1
min := lo.Min([]int{})
// 0Search the minimum value of a collection using the given comparison function.
If several values of the collection are equal to the smallest value, returns the first such value.
Returns zero value when collection is empty.
min := lo.MinBy([]string{"s1", "string2", "s3"}, func(item string, min string) bool {
return len(item) < len(min)
})
// "s1"
min := lo.MinBy([]string{}, func(item string, min string) bool {
return len(item) < len(min)
})
// ""Search the maximum value of a collection.
Returns zero value when collection is empty.
max := lo.Max([]int{1, 2, 3})
// 3
max := lo.Max([]int{})
// 0Search the maximum value of a collection using the given comparison function.
If several values of the collection are equal to the greatest value, returns the first such value.
Returns zero value when collection is empty.
max := lo.MaxBy([]string{"string1", "s2", "string3"}, func(item string, max string) bool {
return len(item) > len(max)
})
// "string1"
max := lo.MaxBy([]string{}, func(item string, max string) bool {
return len(item) > len(max)
})
// ""Returns the last element of a collection or error if empty.
last, err := lo.Last([]int{1, 2, 3})
// 3Returns 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{0, 1, 2, 3}, 2)
// 2
nth, err := lo.Nth([]int{0, 1, 2, 3}, -2)
// 2Returns a random item from collection.
lo.Sample([]string{"a", "b", "c"})
// a random string from []string{"a", "b", "c"}
lo.Sample([]string{})
// ""Returns N random unique items from collection.
lo.Samples([]string{"a", "b", "c"}, 3)
// []string{"a", "b", "c"} in random orderA 1 line if/else statement.
result := lo.Ternary(true, "a", "b")
// "a"
result := lo.Ternary(false, "a", "b")
// "b"[play]
A 1 line if/else statement whose options are functions.
result := lo.TernaryF(true, func() string { return "a" }, func() string { return "b" })
// "a"
result := lo.TernaryF(false, func() string { return "a" }, func() string { return "b" })
// "b"Useful to avoid nil-pointer dereferencing in initializations, or avoid running unnecessary code
var s *string
someStr := TernaryF(s == nil, func() string { return uuid.New().String() }, func() string { return *s })
// ef782193-c30c-4e2e-a7ae-f8ab5e125e02[play]
result := lo.If(true, 1).
ElseIf(false, 2).
Else(3)
// 1
result := lo.If(false, 1).
ElseIf(true, 2).
Else(3)
// 2
result := lo.If(false, 1).
ElseIf(false, 2).
Else(3)
// 3Using callbacks:
result := lo.IfF(true, func () int {
return 1
}).
ElseIfF(false, func () int {
return 2
}).
ElseF(func () int {
return 3
})
// 1Mixed:
result := lo.IfF(true, func () int {
return 1
}).
Else(42)
// 1[play]
result := lo.Switch(1).
Case(1, "1").
Case(2, "2").
Default("3")
// "1"
result := lo.Switch(2).
Case(1, "1").
Case(2, "2").
Default("3")
// "2"
result := lo.Switch(42).
Case(1, "1").
Case(2, "2").
Default("3")
// "3"Using callbacks:
result := lo.Switch(1).
CaseF(1, func() string {
return "1"
}).
CaseF(2, func() string {
return "2"
}).
DefaultF(func() string {
return "3"
})
// "1"Mixed:
result := lo.Switch(1).
CaseF(1, func() string {
return "1"
}).
Default("42")
// "1"[play]
Checks if a value is nil or if it's a reference type with a nil underlying value.
var x int
IsNil(x))
// false
var k struct{}
IsNil(k)
// false
var i *int
IsNil(i)
// true
var ifaceWithNilValue any = (*string)(nil)
IsNil(ifaceWithNilValue)
// true
ifaceWithNilValue == nil
// falseReturns a pointer copy of the value.
ptr := lo.ToPtr("hello world")
// *string{"hello world"}Returns a pointer copy of value if it's nonzero. Otherwise, returns nil pointer.
ptr := lo.EmptyableToPtr[[]int](nil)
// nil
ptr := lo.EmptyableToPtr[string]("")
// nil
ptr := lo.EmptyableToPtr[[]int]([]int{})
// *[]int{}
ptr := lo.EmptyableToPtr[string]("hello world")
// *string{"hello world"}Returns the pointer value or empty.
str := "hello world"
value := lo.FromPtr(&str)
// "hello world"
value := lo.FromPtr[string](nil)
// ""Returns the pointer value or the fallback value.
str := "hello world"
value := lo.FromPtrOr(&str, "empty")
// "hello world"
value := lo.FromPtrOr[string](nil, "empty")
// "empty"Returns a slice of pointer copy of value.
ptr := lo.ToSlicePtr([]string{"hello", "world"})
// []*string{"hello", "world"}Returns a slice with all elements mapped to any type.
elements := lo.ToAnySlice([]int{1, 5, 1})
// []any{1, 5, 1}Returns an any slice with all elements mapped to a type. Returns false in case of type conversion failure.
elements, ok := lo.FromAnySlice([]any{"foobar", 42})
// []string{}, false
elements, ok := lo.FromAnySlice([]any{"foobar", "42"})
// []string{"foobar", "42"}, trueReturns an empty value.
lo.Empty[int]()
// 0
lo.Empty[string]()
// ""
lo.Empty[bool]()
// falseReturns true if argument is a zero value.
lo.IsEmpty(0)
// true
lo.IsEmpty(42)
// false
lo.IsEmpty("")
// true
lo.IsEmpty("foobar")
// false
type test struct {
foobar string
}
lo.IsEmpty(test{foobar: ""})
// true
lo.IsEmpty(test{foobar: "foobar"})
// falseReturns true if argument is a zero value.
lo.IsNotEmpty(0)
// false
lo.IsNotEmpty(42)
// true
lo.IsNotEmpty("")
// false
lo.IsNotEmpty("foobar")
// true
type test struct {
foobar string
}
lo.IsNotEmpty(test{foobar: ""})
// false
lo.IsNotEmpty(test{foobar: "foobar"})
// trueReturns the first non-empty arguments. Arguments must be comparable.
result, ok := lo.Coalesce(0, 1, 2, 3)
// 1 true
result, ok := lo.Coalesce("")
// "" false
var nilStr *string
str := "foobar"
result, ok := lo.Coalesce[*string](nil, nilStr, &str)
// &"foobar" trueReturns new function that, when called, has its first argument set to the provided value.
add := func(x, y int) int { return x + y }
f := lo.Partial(add, 5)
f(10)
// 15
f(42)
// 47Returns new function that, when called, has its first argument set to the provided value.
add := func(x, y, z int) int { return x + y + z }
f := lo.Partial2(add, 42)
f(10, 5)
// 57
f(42, -4)
// 80Invokes a function N times until it returns valid output. Returning either the caught error or nil. When first argument is less than 1, the function runs until a successful response is returned.
iter, err := lo.Attempt(42, func(i int) error {
if i == 5 {
return nil
}
return fmt.Errorf("failed")
})
// 6
// nil
iter, err := lo.Attempt(2, func(i int) error {
if i == 5 {
return nil
}
return fmt.Errorf("failed")
})
// 2
// error "failed"
iter, err := lo.Attempt(0, func(i int) error {
if i < 42 {
return fmt.Errorf("failed")
}
return nil
})
// 43
// nilFor more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.
[play]
Invokes a function N times until it returns valid output, with a pause between each call. Returning either the caught error or nil.
When first argument is less than 1, the function runs until a successful response is returned.
iter, duration, err := lo.AttemptWithDelay(5, 2*time.Second, func(i int, duration time.Duration) error {
if i == 2 {
return nil
}
return fmt.Errorf("failed")
})
// 3
// ~ 4 seconds
// nilFor more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.
[play]
Invokes a function N times until it returns valid output. Returning either the caught error or nil, and along with a bool value to identifying whether it needs invoke function continuously. It will terminate the invoke immediately if second bool value is returned with falsy value.
When first argument is less than 1, the function runs until a successful response is returned.
count1, err1 := lo.AttemptWhile(5, func(i int) (error, bool) {
err := doMockedHTTPRequest(i)
if err != nil {
if errors.Is(err, ErrBadRequest) { // lets assume ErrBadRequest is a critical error that needs to terminate the invoke
return err, false // flag the second return value as false to terminate the invoke
}
return err, true
}
return nil, false
})For more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.
[play]
Invokes a function N times until it returns valid output, with a pause between each call. Returning either the caught error or nil, and along with a bool value to identifying whether it needs to invoke function continuously. It will terminate the invoke immediately if second bool value is returned with falsy value.
When first argument is less than 1, the function runs until a successful response is returned.
count1, time1, err1 := lo.AttemptWhileWithDelay(5, time.Millisecond, func(i int, d time.Duration) (error, bool) {
err := doMockedHTTPRequest(i)
if err != nil {
if errors.Is(err, ErrBadRequest) { // lets assume ErrBadRequest is a critical error that needs to terminate the invoke
return err, false // flag the second return value as false to terminate the invoke
}
return err, true
}
return nil, false
})For more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.
[play]
NewDebounce creates a debounced instance that delays invoking functions given until after wait milliseconds have elapsed, until cancel is called.
f := func() {
println("Called once after 100ms when debounce stopped invoking!")
}
debounce, cancel := lo.NewDebounce(100 * time.Millisecond, f)
for j := 0; j < 10; j++ {
debounce()
}
time.Sleep(1 * time.Second)
cancel()[play]
NewDebounceBy creates a debounced instance for each distinct key, that delays invoking functions given until after wait milliseconds have elapsed, until cancel is called.
f := func(key string, count int) {
println(key + ": Called once after 100ms when debounce stopped invoking!")
}
debounce, cancel := lo.NewDebounceBy(100 * time.Millisecond, f)
for j := 0; j < 10; j++ {
debounce("first key")
debounce("second key")
}
time.Sleep(1 * time.Second)
cancel("first key")
cancel("second key")[play]
Wraps the underlying callback in a mutex. It receives an optional mutex.
s := lo.Synchronize()
for i := 0; i < 10; i++ {
go s.Do(func () {
println("will be called sequentially")
})
}It is equivalent to:
mu := sync.Mutex{}
func foobar() {
mu.Lock()
defer mu.Unlock()
// ...
}Executes a function in a goroutine and returns the result in a channel.
ch := lo.Async(func() error { time.Sleep(10 * time.Second); return nil })
// chan error (nil)Executes a function in a goroutine and returns the result in a channel. For function with multiple return values, the results will be returned as a tuple inside the channel. For function without return, struct{} will be returned in the channel.
ch := lo.Async0(func() { time.Sleep(10 * time.Second) })
// chan struct{}
ch := lo.Async1(func() int {
time.Sleep(10 * time.Second);
return 42
})
// chan int (42)
ch := lo.Async2(func() (int, string) {
time.Sleep(10 * time.Second);
return 42, "Hello"
})
// chan lo.Tuple2[int, string] ({42, "Hello"})Implements a Saga pattern.
transaction := NewTransaction[int]().
Then(
func(state int) (int, error) {
fmt.Println("step 1")
return state + 10, nil
},
func(state int) int {
fmt.Println("rollback 1")
return state - 10
},
).
Then(
func(state int) (int, error) {
fmt.Println("step 2")
return state + 15, nil
},
func(state int) int {
fmt.Println("rollback 2")
return state - 15
},
).
Then(
func(state int) (int, error) {
fmt.Println("step 3")
if true {
return state, fmt.Errorf("error")
}
return state + 42, nil
},
func(state int) int {
fmt.Println("rollback 3")
return state - 42
},
)
_, _ = transaction.Process(-5)
// Output:
// step 1
// step 2
// step 3
// rollback 2
// rollback 1Helper function that creates an error when a condition is not met.
slice := []string{"a"}
val := lo.Validate(len(slice) == 0, "Slice should be empty but contains %v", slice)
// error("Slice should be empty but contains [a]")
slice := []string{}
val := lo.Validate(len(slice) == 0, "Slice should be empty but contains %v", slice)
// nil[play]
Wraps a function call to panics if second argument is error or false, returns the value otherwise.
val := lo.Must(time.Parse("2006-01-02", "2022-01-15"))
// 2022-01-15
val := lo.Must(time.Parse("2006-01-02", "bad-value"))
// panics[play]
Must* has the same behavior as Must, but returns multiple values.
func example0() (error)
func example1() (int, error)
func example2() (int, string, error)
func example3() (int, string, time.Date, error)
func example4() (int, string, time.Date, bool, error)
func example5() (int, string, time.Date, bool, float64, error)
func example6() (int, string, time.Date, bool, float64, byte, error)
lo.Must0(example0())
val1 := lo.Must1(example1()) // alias to Must
val1, val2 := lo.Must2(example2())
val1, val2, val3 := lo.Must3(example3())
val1, val2, val3, val4 := lo.Must4(example4())
val1, val2, val3, val4, val5 := lo.Must5(example5())
val1, val2, val3, val4, val5, val6 := lo.Must6(example6())You can wrap functions like func (...) (..., ok bool).
// math.Signbit(float64) bool
lo.Must0(math.Signbit(v))
// bytes.Cut([]byte,[]byte) ([]byte, []byte, bool)
before, after := lo.Must2(bytes.Cut(s, sep))You can give context to the panic message by adding some printf-like arguments.
val, ok := lo.Find(myString, func(i string) bool {
return i == requiredChar
})
lo.Must0(ok, "'%s' must always contain '%s'", myString, requiredChar)
list := []int{0, 1, 2}
item := 5
lo.Must0(lo.Contains[int](list, item), "'%s' must always contain '%s'", list, item)
...[play]
Calls the function and return false in case of error and on panic.
ok := lo.Try(func() error {
panic("error")
return nil
})
// false
ok := lo.Try(func() error {
return nil
})
// true
ok := lo.Try(func() error {
return fmt.Errorf("error")
})
// false[play]
The same behavior than Try, but callback returns 2 variables.
ok := lo.Try2(func() (string, error) {
panic("error")
return "", nil
})
// false[play]
Calls the function and return a default value in case of error and on panic.
str, ok := lo.TryOr(func() (string, error) {
panic("error")
return "hello", nil
}, "world")
// world
// false
str, ok := lo.TryOr(func() error {
return "hello", nil
}, "world")
// hello
// true
str, ok := lo.TryOr(func() error {
return "hello", fmt.Errorf("error")
}, "world")
// world
// false[play]
The same behavior than TryOr, but callback returns X variables.
str, nbr, ok := lo.TryOr2(func() (string, int, error) {
panic("error")
return "hello", 42, nil
}, "world", 21)
// world
// 21
// false[play]
The same behavior than Try, but also returns value passed to panic.
err, ok := lo.TryWithErrorValue(func() error {
panic("error")
return nil
})
// "error", false[play]
The same behavior than Try, but calls the catch function in case of error.
caught := false
ok := lo.TryCatch(func() error {
panic("error")
return nil
}, func() {
caught = true
})
// false
// caught == true[play]
The same behavior than TryWithErrorValue, but calls the catch function in case of error.
caught := false
ok := lo.TryCatchWithErrorValue(func() error {
panic("error")
return nil
}, func(val any) {
caught = val == "error"
})
// false
// caught == true[play]
A shortcut for:
err := doSomething()
var rateLimitErr *RateLimitError
if ok := errors.As(err, &rateLimitErr); ok {
// retry later
}1 line lo helper:
err := doSomething()
if rateLimitErr, ok := lo.ErrorsAs[*RateLimitError](err); ok {
// retry later
}[play]
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
cpu: Intel(R) Core(TM) i7 CPU 920 @ 2.67GHz
BenchmarkMap/lo.Map-8 8 132728237 ns/op 39998945 B/op 1000002 allocs/op
BenchmarkMap/lop.Map-8 2 503947830 ns/op 119999956 B/op 3000007 allocs/op
BenchmarkMap/reflect-8 2 826400560 ns/op 170326512 B/op 4000042 allocs/op
BenchmarkMap/for-8 9 126252954 ns/op 39998674 B/op 1000001 allocs/op
PASS
ok github.com/samber/lo 6.657slo.Mapis way faster (x7) thango-funk, a reflection-based Map implementation.lo.Maphave the same allocation profile thanfor.lo.Mapis 4% slower thanfor.lop.Mapis slower thanlo.Mapbecause it implies more memory allocation and locks.lop.Mapwill be useful for long-running callbacks, such as i/o bound processing.forbeats 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 ;)
Helper naming: helpers must be self explanatory and respect standards (other languages, libraries...). Feel free to suggest many names in your contributions.
docker-compose run --rm dev# Install some dev dependencies
make tools
# Run tests
make test
# or
make watch-testGive a ⭐️ if this project helped you!
Copyright © 2022 Samuel Berthe.
This project is MIT licensed.