lo

package module
Version: v1.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 10, 2022 License: MIT Imports: 7 Imported by: 152

README

lo

Build Status GoDoc Go report

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 will be 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.

Why this name?

I wanted a short name, similar to "Lodash" and no Go package currently uses this name.

🚀 Install

go get github.com/samber/lo@v1

This library is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before v2.0.0.

💡 Usage

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", "Marc", "Samuel"})
// []string{"Samuel", "Marc"}

Most of the time, the compiler will be able to infer the type so that you can call: lo.Uniq([]string{...}).

🤠 Spec

GoDoc: https://godoc.org/github.com/samber/lo

Supported helpers for slices:

  • Filter
  • Map
  • FilterMap
  • FlatMap
  • Reduce
  • ForEach
  • Times
  • Uniq
  • UniqBy
  • GroupBy
  • Chunk
  • PartitionBy
  • Flatten
  • Shuffle
  • Reverse
  • Fill
  • Repeat
  • KeyBy
  • Drop
  • DropRight
  • DropWhile
  • DropRightWhile
  • Reject
  • Count
  • CountBy

Supported helpers for maps:

  • Keys
  • Values
  • PickBy
  • PickByKeys
  • PickByValues
  • OmitBy
  • OmitByKeys
  • OmitByValues
  • Entries
  • FromEntries
  • Invert
  • Assign (merge of maps)
  • MapKeys
  • MapValues

Supported math helpers:

  • Range / RangeFrom / RangeWithSteps
  • Clamp
  • SumBy

Supported helpers for strings:

  • Substring
  • RuneLength

Supported helpers for tuples:

  • T2 -> T9
  • Unpack2 -> Unpack9
  • Zip2 -> Zip9
  • Unzip2 -> Unzip9

Supported intersection helpers:

  • Contains
  • ContainsBy
  • Every
  • EveryBy
  • Some
  • SomeBy
  • None
  • NoneBy
  • Intersect
  • Difference
  • Union

Supported search helpers:

  • IndexOf
  • LastIndexOf
  • Find
  • FindIndexOf
  • FindLastIndexOf
  • Min
  • MinBy
  • Max
  • MaxBy
  • Last
  • Nth
  • Sample
  • Samples

Conditional helpers:

  • Ternary (1 line if/else statement)
  • If / ElseIf / Else
  • Switch / Case / Default

Type manipulation helpers:

  • ToPtr
  • ToSlicePtr
  • ToAnySlice
  • FromAnySlice
  • Empty
  • Coalesce

Concurrency helpers:

  • Attempt
  • AttemptWithDelay
  • Debounce
  • Async

Error handling:

  • Must
  • Try
  • TryCatch
  • TryWithErrorValue
  • TryCatchWithErrorValue

Constraints:

  • Clonable
Map

Manipulates a slice of one type and transforms it into 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 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, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
    return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}
FlatMap

Manipulates a slice and transforms and flattens it to a slice of another type.

lo.FlatMap[int, string]([]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"}
FilterMap

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, string]([]string{"cpu", "gpu", "mouse", "keyboard"}, func(x string, _ int) (string, bool) {
    if strings.HasSuffix(x, "pu") {
        return "xpu", true
    }
    return "", false
})
// []string{"xpu", "xpu"}
Filter

Iterates over a collection and returns an array of all the elements the predicate function returns true for.

even := lo.Filter[int]([]int{1, 2, 3, 4}, func(x int, _ int) bool {
    return x%2 == 0
})
// []int{2, 4}
Contains

Returns true if an element is present in a collection.

present := lo.Contains[int]([]int{0, 1, 2, 3, 4, 5}, 5)
// true
ContainsBy

Returns true if the predicate function returns true.

present := lo.ContainsBy[int]([]int{0, 1, 2, 3, 4, 5}, func(x int) bool {
    return x == 3
})
// true
Reduce

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, int]([]int{1, 2, 3, 4}, func(agg int, item int, _ int) int {
    return agg + item
}, 0)
// 10
ForEach

Iterates over elements of a collection and invokes the function over 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 the callback is called as a 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"
Times

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[string](3, func(i int) string {
    return strconv.FormatInt(int64(i), 10)
})
// []string{"0", "1", "2"}

Parallel processing: like lo.Times(), but callback is called in goroutine.

import lop "github.com/samber/lo/parallel"

lop.Times[string](3, func(i int) string {
    return strconv.FormatInt(int64(i), 10)
})
// []string{"0", "1", "2"}
Uniq

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}
UniqBy

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}
GroupBy

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, 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}}

Parallel processing: like lo.GroupBy(), but callback is called in goroutine.

import lop "github.com/samber/lo/parallel"

lop.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}}
Chunk

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}}
PartitionBy

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, string]([]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}}

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 := lo.PartitionBy[int, string]([]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}}
Flatten

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}
Shuffle

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}
Reverse

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}
Fill

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"}}
Repeat

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[foo](2, foo{"a"})
// []foo{foo{"a"}, foo{"a"}}
RepeatBy

Builds a slice with values returned by N calls of callback.

slice := lo.RepeatBy[int](0, func (i int) int {
    return math.Pow(i, 2)
})
// []int{}

slice := lo.RepeatBy[int](5, func (i int) int {
    return math.Pow(i, 2)
})
// []int{0, 1, 4, 9, 16}
KeyBy

Transforms a slice or an array of structs to a map based on a pivot callback.

m := lo.KeyBy[int, string]([]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[string, Character](characters, func(char Character) string {
    return string(rune(char.code))
})
//map[a:{dir:left code:97} d:{dir:right code:100}]
Drop

Drops n elements from the beginning of a slice or array.

l := lo.Drop[int]([]int{0, 1, 2, 3, 4, 5}, 2)
// []int{2, 3, 4, 5}
DropRight

Drops n elements from the end of a slice or array.

l := lo.DropRight[int]([]int{0, 1, 2, 3, 4, 5}, 2)
// []int{0, 1, 2, 3}
DropWhile

Drop elements from the beginning of a slice or array while the predicate returns true.

l := lo.DropWhile[string]([]string{"a", "aa", "aaa", "aa", "aa"}, func(val string) bool {
	return len(val) <= 2
})
// []string{"aaa", "aa", "aa"}
DropRightWhile

Drop elements from the end of a slice or array while the predicate returns true.

l := lo.DropRightWhile[string]([]string{"a", "aa", "aaa", "aa", "aa"}, func(val string) bool {
	return len(val) <= 2
})
// []string{"a", "aa", "aaa"}
Reject

The opposite of Filter, this method returns the elements of collection that predicate does not return truthy for.

odd := lo.Reject[int]([]int{1, 2, 3, 4}, func(x int, _ int) bool {
    return x%2 == 0
})
// []int{1, 3}
Count

Counts the number of elements in the collection that compare equal to value.

count := lo.Count[int]([]int{1, 5, 1}, 1)
// 2
CountBy

Counts the number of elements in the collection for which predicate is true.

count := lo.CountBy[int]([]int{1, 5, 1}, func(i int) bool {
    return i < 4
})
// 2
Subset

Return part of a slice.

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}
Replace

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}
ReplaceAll

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}
Keys

Creates an array of the map keys.

keys := lo.Keys[string, int](map[string]int{"foo": 1, "bar": 2})
// []string{"bar", "foo"}
Values

Creates an array of the map values.

values := lo.Values[string, int](map[string]int{"foo": 1, "bar": 2})
// []int{1, 2}
PickBy

Returns same map type filtered by given predicate.

m := lo.PickBy[string, int](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}
PickByKeys

Returns same map type filtered by given keys.

m := lo.PickByKeys[string, int](map[string]int{"foo": 1, "bar": 2, "baz": 3}, []string{"foo", "baz"})
// map[string]int{"foo": 1, "baz": 3}
PickByValues

Returns same map type filtered by given values.

m := lo.PickByValues[string, int](map[string]int{"foo": 1, "bar": 2, "baz": 3}, []int{1, 3})
// map[string]int{"foo": 1, "baz": 3}
OmitBy

Returns same map type filtered by given predicate.

m := lo.OmitBy[string, int](map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(key string, value int) bool {
    return value%2 == 1
})
// map[string]int{"bar": 2}
OmitByKeys

Returns same map type filtered by given keys.

m := lo.OmitByKeys[string, int](map[string]int{"foo": 1, "bar": 2, "baz": 3}, []string{"foo", "baz"})
// map[string]int{"bar": 2}
OmitByValues

Returns same map type filtered by given values.

m := lo.OmitByValues[string, int](map[string]int{"foo": 1, "bar": 2, "baz": 3}, []int{1, 3})
// map[string]int{"bar": 2}
Entries

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,
//     },
// }
FromEntries

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}
Invert

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[string, int]([map[string]int{"a": 1, "b": 2})
// map[int]string{1: "a", 2: "b"}

m2 := lo.Invert[string, int]([map[string]int{"a": 1, "b": 2, "c": 1})
// map[int]string{1: "c", 2: "b"}
Assign

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}
MapKeys

Manipulates a map keys and transforms it to a map of another type.

m2 := lo.MapKeys[int, int, string](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}
MapValues

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[int, int64, string](m1, func(x int64, _ int) string {
	return strconv.FormatInt(x, 10)
})
// map[int]string{1: "1", 2: "2", 3: "3"}
Range / RangeFrom / RangeWithSteps

Creates an array of numbers (positive and/or negative) progressing from start up to, but not including end.

result := Range(4)
// [0, 1, 2, 3]

result := Range(-4);
// [0, -1, -2, -3]

result := RangeFrom(1, 5);
// [1, 2, 3, 4]

result := RangeFrom[float64](1.0, 5);
// [1.0, 2.0, 3.0, 4.0]

result := RangeWithSteps(0, 20, 5);
// [0, 5, 10, 15]

result := RangeWithSteps[float32](-1.0, -4.0, -1.0);
// [-1.0, -2.0, -3.0]

result := RangeWithSteps(1, 4, -1);
// []

result := Range(0);
// []
Clamp

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
SumBy

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
Substring

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"
RuneLength

An alias to utf8.RuneCountInString which returns the number of runes in string.

sub := lo.RuneLength("hellô")
// 5

sub := len("hellô")
// 6
T2 -> T9

Creates a tuple from a list of values.

tuple1 := lo.T2[string, int]("x", 1)
// Tuple2[string, int]{A: "x", B: 1}

func example() (string, int) { return "y", 2 }
tuple2 := lo.T2[string, int](example())
// Tuple2[string, int]{A: "y", B: 2}
Unpack2 -> Unpack9

Returns values contained in tuple.

r1, r2 := lo.Unpack2[string, int](lo.Tuple2[string, int]{"a", 1})
// "a", 1
Zip2 -> Zip9

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, int]([]string{"a", "b"}, []int{1, 2})
// []Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}}
Unzip2 -> Unzip9

Unzip accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

a, b := lo.Unzip2[string, int]([]Tuple2[string, int]{{A: "a", B: 1}, {A: "b", B: 2}})
// []string{"a", "b"}
// []int{1, 2}
Every

Returns true if all elements of a subset are contained into a collection or if the subset is empty.

ok := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true

ok := lo.Every[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// false
EveryBy

Returns true if the predicate returns true for all of the elements in the collection or if the collection is empty.

b := EveryBy[int]([]int{1, 2, 3, 4}, func(x int) bool {
    return x < 5
})
// true
Some

Returns 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]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// true

ok := lo.Some[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// false
SomeBy

Returns 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]([]int{1, 2, 3, 4}, func(x int) bool {
    return x < 3
})
// true
None

Returns true if no element of a subset are contained into a collection or if the subset is empty.

b := None[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// false
b := None[int]([]int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// true
NoneBy

Returns true if the predicate returns true for none of the elements in the collection or if the collection is empty.

b := NoneBy[int]([]int{1, 2, 3, 4}, func(x int) bool {
    return x < 0
})
// true
Intersect

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{}
Difference

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 := lo.Difference[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 1, 2, 3, 4, 5})
// []int{}, []int{}
Union

Returns all distinct elements from both collections. Result will not change the order of elements relatively.

union := lo.Union[int]([]int{0, 1, 2, 3, 4, 5}, []int{0, 2, 10})
// []int{0, 1, 2, 3, 4, 5, 10}
IndexOf

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
LastIndex

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
Find

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
FindIndexOf

FindIndexOf 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]([]string{"a", "b", "a", "b"}, func(i string) bool {
    return i == "b"
})
// "b", 1, true

str, index, ok := lo.FindIndexOf[string]([]string{"foobar"}, func(i string) bool {
    return i == "b"
})
// "", -1, false
FindLastIndexOf

FindLastIndexOf 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]([]string{"a", "b", "a", "b"}, func(i string) bool {
    return i == "b"
})
// "b", 4, true

str, index, ok := lo.FindLastIndexOf[string]([]string{"foobar"}, func(i string) bool {
    return i == "b"
})
// "", -1, false
Min

Search the minimum value of a collection.

min := lo.Min[int]([]int{1, 2, 3})
// 1

min := lo.Min[int]([]int{})
// 0
MinBy

Search 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.

min := lo.MinBy[string]([]string{"s1", "string2", "s3"}, func(item string, min string) bool {
    return len(item) < len(min)
})
// "s1"

min := lo.MinBy[string]([]string{}, func(item string, min string) bool {
    return len(item) < len(min)
})
// ""
Max

Search the maximum value of a collection.

max := lo.Max[int]([]int{1, 2, 3})
// 3

max := lo.Max[int]([]int{})
// 0
MaxBy

Search 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.

max := lo.MaxBy[string]([]string{"string1", "s2", "string3"}, func(item string, max string) bool {
    return len(item) > len(max)
})
// "string1"

max := lo.MaxBy[string]([]string{}, func(item string, max string) bool {
    return len(item) > len(max)
})
// ""
Last

Returns the last element of a collection or error if empty.

last, err := lo.Last[int]([]int{1, 2, 3})
// 3
Nth

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
Sample

Returns a random item from collection.

lo.Sample[string]([]string{"a", "b", "c"})
// a random string from []string{"a", "b", "c"}

lo.Sample[string]([]string{})
// ""
Samples

Returns N random unique items from collection.

lo.Samples[string]([]string{"a", "b", "c"}, 3)
// []string{"a", "b", "c"} in random order
Ternary

A 1 line if/else statement.

result := lo.Ternary[string](true, "a", "b")
// "a"

result := lo.Ternary[string](false, "a", "b")
// "b"
If / ElseIf / Else
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

Using callbacks:

result := lo.IfF[int](true, func () int {
        return 1
    }).
    ElseIfF(false, func () int {
        return 2
    }).
    ElseF(func () int {
        return 3
    })
// 1

Mixed:

result := lo.IfF[int](true, func () int {
        return 1
    }).
    Else(42)
// 1
Switch / Case / Default
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"

Mixed:

result := lo.Switch[int, string](1).
    CaseF(1, func() string {
        return "1"
    }).
    Default("42")
// "1"
ToPtr

Returns a pointer copy of value.

ptr := lo.ToPtr[string]("hello world")
// *string{"hello world"}
ToSlicePtr

Returns a slice of pointer copy of value.

ptr := lo.ToSlicePtr[string]([]string{"hello", "world"})
// []*string{"hello", "world"}
ToAnySlice

Returns a slice with all elements mapped to any type.

elements := lo.ToAnySlice[int]([]int{1, 5, 1})
// []any{1, 5, 1}
FromAnySlice

Returns an any slice with all elements mapped to a type. Returns false in case of type conversion failure.

elements, ok := lo.FromAnySlice[string]([]any{"foobar", 42})
// []string{}, false

elements, ok := lo.FromAnySlice[string]([]any{"foobar", "42"})
// []string{"foobar", "42"}, true
Empty

Returns an empty value.

lo.Empty[int]()
// 0
lo.Empty[string]()
// ""
lo.Empty[bool]()
// false
Coalesce

Returns 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" true
Attempt

Invokes 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 sucessfull 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
// nil

For more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.

AttemptWithDelay

Invokes a function N times until it returns valid output, with a pause betwwen each call. Returning either the caught error or nil.

When first argument is less than 1, the function runs until a sucessfull 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
// nil

For more advanced retry strategies (delay, exponential backoff...), please take a look on cenkalti/backoff.

Debounce

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()
Synchronize

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()

    // ...
}
Async

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)
Async{0->6}

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"})
Must

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
Must{0->6}

Must* has the same behavior than 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))

Try

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

Try{0->6}

The same behavior than Try, but callback returns 2 variables.

ok := lo.Try2(func() (string, error) {
    panic("error")
    return "", nil
})
// false

TryWithErrorValue

The same behavior than Try, but also returns value passed to panic.

err, ok := lo.TryWithErrorValue(func() error {
    panic("error")
    return nil
})
// "error", false

TryCatch

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

TryCatchWithErrorValue

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

🛩 Benchmark

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.657s
  • lo.Map is way faster (x7) than go-funk, a relection-based Map implementation.
  • lo.Map have the same allocation profile than for.
  • lo.Map is 4% slower than for.
  • lop.Map is slower than lo.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.

🤝 Contributing

Don't hesitate ;)

Install go 1.18
make go1.18beta1

If your OS currently not default to Go 1.18, replace BIN=go by BIN=go1.18beta1 in the Makefile.

With Docker
docker-compose run --rm dev
Without Docker
# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

👤 Authors

  • Samuel Berthe

💫 Show your support

Give a ⭐️ if this project helped you!

support us

📝 License

Copyright © 2022 Samuel Berthe.

This project is MIT licensed.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Assign

func Assign[K comparable, V any](maps ...map[K]V) map[K]V

Assign merges multiple maps from left to right.

func Async added in v1.12.0

func Async[A any](f func() A) chan A

Async executes a function in a goroutine and returns the result in a channel.

func Async0 added in v1.17.0

func Async0(f func()) chan struct{}

Async0 executes a function in a goroutine and returns a channel set once the function finishes.

func Async1 added in v1.17.0

func Async1[A any](f func() A) chan A

Async1 is an alias to Async.

func Async2 added in v1.17.0

func Async2[A any, B any](f func() (A, B)) chan Tuple2[A, B]

Async2 has the same behavior as Async, but returns the 2 results as a tuple inside the channel.

func Async3 added in v1.17.0

func Async3[A any, B any, C any](f func() (A, B, C)) chan Tuple3[A, B, C]

Async3 has the same behavior as Async, but returns the 3 results as a tuple inside the channel.

func Async4 added in v1.17.0

func Async4[A any, B any, C any, D any](f func() (A, B, C, D)) chan Tuple4[A, B, C, D]

Async4 has the same behavior as Async, but returns the 4 results as a tuple inside the channel.

func Async5 added in v1.17.0

func Async5[A any, B any, C any, D any, E any](f func() (A, B, C, D, E)) chan Tuple5[A, B, C, D, E]

Async5 has the same behavior as Async, but returns the 5 results as a tuple inside the channel.

func Async6 added in v1.17.0

func Async6[A any, B any, C any, D any, E any, F any](f func() (A, B, C, D, E, F)) chan Tuple6[A, B, C, D, E, F]

Async6 has the same behavior as Async, but returns the 6 results as a tuple inside the channel.

func Attempt added in v1.5.0

func Attempt(maxIteration int, f func(int) error) (int, error)

Attempt invokes 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 sucessfull response is returned.

func AttemptWithDelay added in v1.16.0

func AttemptWithDelay(maxIteration int, delay time.Duration, f func(int, time.Duration) error) (int, time.Duration, error)

AttemptWithDelay invokes a function N times until it returns valid output, with a pause betwwen each call. Returning either the caught error or nil. When first argument is less than `1`, the function runs until a sucessfull response is returned.

func Chunk

func Chunk[T any](collection []T, size int) [][]T

Chunk 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.

func Clamp added in v1.13.0

func Clamp[T constraints.Ordered](value T, min T, max T) T

Clamp clamps number within the inclusive lower and upper bounds.

func Coalesce added in v1.14.0

func Coalesce[T comparable](v ...T) (result T, ok bool)

Coalesce returns the first non-empty arguments. Arguments must be comparable.

func Contains

func Contains[T comparable](collection []T, element T) bool

Contains returns true if an element is present in a collection.

func ContainsBy added in v1.7.0

func ContainsBy[T any](collection []T, predicate func(T) bool) bool

ContainsBy returns true if predicate function return true.

func Count added in v1.12.0

func Count[T comparable](collection []T, value T) (count int)

Count counts the number of elements in the collection that compare equal to value.

func CountBy added in v1.12.0

func CountBy[T any](collection []T, predicate func(T) bool) (count int)

CountBy counts the number of elements in the collection for which predicate is true.

func Difference

func Difference[T comparable](list1 []T, list2 []T) ([]T, []T)

Difference 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.

func Drop added in v1.9.0

func Drop[T any](collection []T, n int) []T

Drop drops n elements from the beginning of a slice or array.

func DropRight added in v1.9.0

func DropRight[T any](collection []T, n int) []T

DropRight drops n elements from the end of a slice or array.

func DropRightWhile added in v1.9.0

func DropRightWhile[T any](collection []T, predicate func(T) bool) []T

DropRightWhile drops elements from the end of a slice or array while the predicate returns true.

func DropWhile added in v1.9.0

func DropWhile[T any](collection []T, predicate func(T) bool) []T

DropWhile drops elements from the beginning of a slice or array while the predicate returns true.

func Empty added in v1.6.0

func Empty[T any]() T

Empty returns an empty value.

func Every

func Every[T comparable](collection []T, subset []T) bool

Every returns true if all elements of a subset are contained into a collection or if the subset is empty.

func EveryBy added in v1.18.0

func EveryBy[V any](collection []V, predicate func(V) bool) bool

EveryBy returns true if the predicate returns true for all of the elements in the collection or if the collection is empty.

func Fill

func Fill[T Clonable[T]](collection []T, initial T) []T

Fill fills elements of array with `initial` value.

func Filter

func Filter[V any](collection []V, predicate func(V, int) bool) []V

Filter iterates over elements of collection, returning an array of all elements predicate returns truthy for.

func FilterMap added in v1.12.0

func FilterMap[T any, R any](collection []T, callback func(T, int) (R, bool)) []R

FilterMap 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.

func Find

func Find[T any](collection []T, predicate func(T) bool) (T, bool)

Find search an element in a slice based on a predicate. It returns element and true if element was found.

func FindIndexOf added in v1.12.0

func FindIndexOf[T any](collection []T, predicate func(T) bool) (T, int, bool)

FindIndexOf 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.

func FindLastIndexOf added in v1.12.0

func FindLastIndexOf[T any](collection []T, predicate func(T) bool) (T, int, bool)

FindLastIndexOf searches last 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.

func FindOrElse added in v1.12.0

func FindOrElse[T any](collection []T, fallback T, predicate func(T) bool) T

FindOrElse search an element in a slice based on a predicate. It returns the element if found or a given fallback value otherwise.

func FlatMap added in v1.7.0

func FlatMap[T any, R any](collection []T, iteratee func(T, int) []R) []R

FlatMap manipulates a slice and transforms and flattens it to a slice of another type.

func Flatten

func Flatten[T any](collection [][]T) []T

Flatten returns an array a single level deep.

func ForEach

func ForEach[T any](collection []T, iteratee func(T, int))

ForEach iterates over elements of collection and invokes iteratee for each element.

func FromAnySlice added in v1.21.0

func FromAnySlice[T any](in []any) (out []T, ok bool)

FromAnySlice returns an `any` slice with all elements mapped to a type. Returns false in case of type conversion failure.

func FromEntries

func FromEntries[K comparable, V any](entries []Entry[K, V]) map[K]V

FromEntries transforms an array of key/value pairs into a map.

func GroupBy

func GroupBy[T any, U comparable](collection []T, iteratee func(T) U) map[U][]T

GroupBy returns an object composed of keys generated from the results of running each element of collection through iteratee.

func If

func If[T any](condition bool, result T) *ifElse[T]

If.

func IfF added in v1.13.0

func IfF[T any](condition bool, resultF func() T) *ifElse[T]

IfF.

func IndexOf

func IndexOf[T comparable](collection []T, element T) int

IndexOf 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.

func Intersect

func Intersect[T comparable](list1 []T, list2 []T) []T

Intersect returns the intersection between two collections.

func Invert added in v1.13.0

func Invert[K comparable, V comparable](in map[K]V) map[V]K

Invert creates a map composed of the inverted keys and values. If map contains duplicate values, subsequent values overwrite property assignments of previous values.

func KeyBy added in v1.10.1

func KeyBy[K comparable, V any](collection []V, iteratee func(V) K) map[K]V

KeyBy transforms a slice or an array of structs to a map based on a pivot callback.

func Keys

func Keys[K comparable, V any](in map[K]V) []K

Keys creates an array of the map keys.

func Last

func Last[T any](collection []T) (T, error)

Last returns the last element of a collection or error if empty.

func LastIndexOf

func LastIndexOf[T comparable](collection []T, element T) int

LastIndexOf 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.

func Map

func Map[T any, R any](collection []T, iteratee func(T, int) R) []R

Map manipulates a slice and transforms it to a slice of another type.

func MapKeys added in v1.13.0

func MapKeys[K comparable, V any, R comparable](in map[K]V, iteratee func(V, K) R) map[R]V

MapKeys manipulates a map keys and transforms it to a map of another type.

func MapValues added in v1.7.0

func MapValues[K comparable, V any, R any](in map[K]V, iteratee func(V, K) R) map[K]R

MapValues manipulates a map values and transforms it to a map of another type.

func Max

func Max[T constraints.Ordered](collection []T) T

Max searches the maximum value of a collection.

func MaxBy added in v1.12.0

func MaxBy[T any](collection []T, comparison func(T, T) bool) T

MaxBy search 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.

func Min

func Min[T constraints.Ordered](collection []T) T

Min search the minimum value of a collection.

func MinBy added in v1.12.0

func MinBy[T any](collection []T, comparison func(T, T) bool) T

MinBy search 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.

func Must added in v1.12.0

func Must[T any](val T, err any) T

Must is a helper that wraps a call to a function returning a value and an error and panics if err is error or false.

func Must0 added in v1.12.0

func Must0(err any)

Must0 has the same behavior than Must, but callback returns no variable.

func Must1 added in v1.12.0

func Must1[T any](val T, err any) T

Must1 is an alias to Must

func Must2 added in v1.12.0

func Must2[T1 any, T2 any](val1 T1, val2 T2, err any) (T1, T2)

Must2 has the same behavior than Must, but callback returns 2 variables.

func Must3 added in v1.12.0

func Must3[T1 any, T2 any, T3 any](val1 T1, val2 T2, val3 T3, err any) (T1, T2, T3)

Must3 has the same behavior than Must, but callback returns 3 variables.

func Must4 added in v1.12.0

func Must4[T1 any, T2 any, T3 any, T4 any](val1 T1, val2 T2, val3 T3, val4 T4, err any) (T1, T2, T3, T4)

Must4 has the same behavior than Must, but callback returns 4 variables.

func Must5 added in v1.12.0

func Must5[T1 any, T2 any, T3 any, T4 any, T5 any](val1 T1, val2 T2, val3 T3, val4 T4, val5 T5, err any) (T1, T2, T3, T4, T5)

Must5 has the same behavior than Must, but callback returns 5 variables.

func Must6 added in v1.12.0

func Must6[T1 any, T2 any, T3 any, T4 any, T5 any, T6 any](val1 T1, val2 T2, val3 T3, val4 T4, val5 T5, val6 T6, err any) (T1, T2, T3, T4, T5, T6)

Must6 has the same behavior than Must, but callback returns 6 variables.

func NewDebounce added in v1.11.0

func NewDebounce(duration time.Duration, f ...func()) (func(), func())

NewDebounce creates a debounced instance that delays invoking functions given until after wait milliseconds have elapsed.

func None added in v1.18.0

func None[V comparable](collection []V, subset []V) bool

None returns true if no element of a subset are contained into a collection or if the subset is empty.

func NoneBy added in v1.18.0

func NoneBy[V any](collection []V, predicate func(V) bool) bool

NoneBy returns true if the predicate returns true for none of the elements in the collection or if the collection is empty.

func Nth

func Nth[T any](collection []T, nth int) (T, error)

Nth 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.

func OmitBy added in v1.13.0

func OmitBy[K comparable, V any](in map[K]V, predicate func(K, V) bool) map[K]V

PickBy returns same map type filtered by given predicate.

func OmitByKeys added in v1.13.0

func OmitByKeys[K comparable, V any](in map[K]V, keys []K) map[K]V

OmitByKeys returns same map type filtered by given keys.

func OmitByValues added in v1.13.0

func OmitByValues[K comparable, V comparable](in map[K]V, values []V) map[K]V

OmitByValues returns same map type filtered by given values.

func PartitionBy added in v1.4.0

func PartitionBy[T any, K comparable](collection []T, iteratee func(x T) K) [][]T

PartitionBy 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.

func PickBy added in v1.13.0

func PickBy[K comparable, V any](in map[K]V, predicate func(K, V) bool) map[K]V

PickBy returns same map type filtered by given predicate.

func PickByKeys added in v1.13.0

func PickByKeys[K comparable, V any](in map[K]V, keys []K) map[K]V

PickByKeys returns same map type filtered by given keys.

func PickByValues added in v1.13.0

func PickByValues[K comparable, V comparable](in map[K]V, values []V) map[K]V

PickByValues returns same map type filtered by given values.

func Range added in v1.10.0

func Range(elementNum int) []int

Range creates an array of numbers (positive and/or negative) with given length.

func RangeFrom added in v1.10.0

func RangeFrom[T constraints.Integer | constraints.Float](start T, elementNum int) []T

RangeFrom creates an array of numbers from start with specified length.

func RangeWithSteps added in v1.10.0

func RangeWithSteps[T constraints.Integer | constraints.Float](start, end, step T) []T

RangeWithSteps creates an array of numbers (positive and/or negative) progressing from start up to, but not including end. step set to zero will return empty array.

func Reduce

func Reduce[T any, R any](collection []T, accumulator func(R, T, int) R, initial R) R

Reduce 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.

func Reject added in v1.11.0

func Reject[V any](collection []V, predicate func(V, int) bool) []V

Reject is the opposite of Filter, this method returns the elements of collection that predicate does not return truthy for.

func Repeat added in v1.5.0

func Repeat[T Clonable[T]](count int, initial T) []T

Repeat builds a slice with N copies of initial value.

func RepeatBy added in v1.19.0

func RepeatBy[T any](count int, predicate func(int) T) []T

RepeatBy builds a slice with values returned by N calls of callback.

func Replace added in v1.19.0

func Replace[T comparable](collection []T, old T, new T, n int) []T

Replace returns a copy of the slice with the first n non-overlapping instances of old replaced by new.

func ReplaceAll added in v1.19.0

func ReplaceAll[T comparable](collection []T, old T, new T) []T

ReplaceAll returns a copy of the slice with all non-overlapping instances of old replaced by new.

func Reverse

func Reverse[T any](collection []T) []T

Reverse reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.

func RuneLength added in v1.19.0

func RuneLength(str string) int

RuneLength is an alias to utf8.RuneCountInString which returns the number of runes in string.

func Sample added in v1.6.0

func Sample[T any](collection []T) T

Sample returns a random item from collection.

func Samples added in v1.6.0

func Samples[T any](collection []T, count int) []T

Samples returns N random unique items from collection.

func Shuffle

func Shuffle[T any](collection []T) []T

Shuffle returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.

func Some

func Some[T comparable](collection []T, subset []T) bool

Some returns true if at least 1 element of a subset is contained into a collection. If the subset is empty Some returns false.

func SomeBy added in v1.18.0

func SomeBy[V any](collection []V, predicate func(V) bool) bool

SomeBy returns true if the predicate returns true for any of the elements in the collection. If the collection is empty SomeBy returns false.

func Subset added in v1.19.0

func Subset[T any](collection []T, offset int, length uint) []T

Subset return part of a slice.

func Substring added in v1.19.0

func Substring[T ~string](str T, offset int, length uint) T

Substring return part of a string.

func SumBy added in v1.20.0

func SumBy[T any, R constraints.Float | constraints.Integer](collection []T, iteratee func(T) R) R

Summarizes the values in a collection.

func Switch

func Switch[T comparable, R any](predicate T) *switchCase[T, R]

Switch is a pure functional switch/case/default statement.

func Synchronize added in v1.20.0

func Synchronize(opt ...sync.Locker) *synchronize

Synchronize wraps the underlying callback in a mutex. It receives an optional mutex.

func Ternary

func Ternary[T any](condition bool, ifOutput T, elseOutput T) T

Ternary is a 1 line if/else statement.

func Times added in v1.5.0

func Times[T any](count int, iteratee func(int) T) []T

Times invokes the iteratee n times, returning an array of the results of each invocation. The iteratee is invoked with index as argument.

func ToAnySlice added in v1.21.0

func ToAnySlice[T any](collection []T) []any

ToAnySlice returns a slice with all elements mapped to `any` type

func ToPtr

func ToPtr[T any](x T) *T

ToPtr returns a pointer copy of value.

func ToSlicePtr

func ToSlicePtr[T any](collection []T) []*T

ToSlicePtr returns a slice of pointer copy of value.

func Try added in v1.11.0

func Try(callback func() error) (ok bool)

Try calls the function and return false in case of error.

func Try0 added in v1.11.0

func Try0(callback func()) bool

Try0 has the same behavior than Try, but callback returns no variable.

func Try1 added in v1.11.0

func Try1[T any](callback func() error) bool

Try1 is an alias to Try.

func Try2 added in v1.11.0

func Try2[T any](callback func() (T, error)) bool

Try2 has the same behavior than Try, but callback returns 2 variables.

func Try3 added in v1.11.0

func Try3[T, R any](callback func() (T, R, error)) bool

Try3 has the same behavior than Try, but callback returns 3 variables.

func Try4 added in v1.11.0

func Try4[T, R, S any](callback func() (T, R, S, error)) bool

Try4 has the same behavior than Try, but callback returns 4 variables.

func Try5 added in v1.11.0

func Try5[T, R, S, Q any](callback func() (T, R, S, Q, error)) bool

Try5 has the same behavior than Try, but callback returns 5 variables.

func Try6 added in v1.11.0

func Try6[T, R, S, Q, U any](callback func() (T, R, S, Q, U, error)) bool

Try6 has the same behavior than Try, but callback returns 6 variables.

func TryCatch added in v1.11.0

func TryCatch(callback func() error, catch func())

TryCatch has the same behavior than Try, but calls the catch function in case of error.

func TryCatchWithErrorValue added in v1.11.0

func TryCatchWithErrorValue(callback func() error, catch func(any))

TryCatchWithErrorValue has the same behavior than TryWithErrorValue, but calls the catch function in case of error.

func TryWithErrorValue added in v1.11.0

func TryWithErrorValue(callback func() error) (errorValue any, ok bool)

TryWithErrorValue has the same behavior than Try, but also returns value passed to panic.

func Union added in v1.8.0

func Union[T comparable](list1 []T, list2 []T) []T

Union returns all distinct elements from both collections. result returns will not change the order of elements relatively.

func Uniq

func Uniq[T comparable](collection []T) []T

Uniq 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.

func UniqBy

func UniqBy[T any, U comparable](collection []T, iteratee func(T) U) []T

UniqBy 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.

func Unpack2 added in v1.17.0

func Unpack2[A any, B any](tuple Tuple2[A, B]) (A, B)

Unpack2 returns values contained in tuple.

func Unpack3 added in v1.17.0

func Unpack3[A any, B any, C any](tuple Tuple3[A, B, C]) (A, B, C)

Unpack3 returns values contained in tuple.

func Unpack4 added in v1.17.0

func Unpack4[A any, B any, C any, D any](tuple Tuple4[A, B, C, D]) (A, B, C, D)

Unpack4 returns values contained in tuple.

func Unpack5 added in v1.17.0

func Unpack5[A any, B any, C any, D any, E any](tuple Tuple5[A, B, C, D, E]) (A, B, C, D, E)

Unpack5 returns values contained in tuple.

func Unpack6 added in v1.17.0

func Unpack6[A any, B any, C any, D any, E any, F any](tuple Tuple6[A, B, C, D, E, F]) (A, B, C, D, E, F)

Unpack6 returns values contained in tuple.

func Unpack7 added in v1.17.0

func Unpack7[A any, B any, C any, D any, E any, F any, G any](tuple Tuple7[A, B, C, D, E, F, G]) (A, B, C, D, E, F, G)

Unpack7 returns values contained in tuple.

func Unpack8 added in v1.17.0

func Unpack8[A any, B any, C any, D any, E any, F any, G any, H any](tuple Tuple8[A, B, C, D, E, F, G, H]) (A, B, C, D, E, F, G, H)

Unpack8 returns values contained in tuple.

func Unpack9 added in v1.17.0

func Unpack9[A any, B any, C any, D any, E any, F any, G any, H any, I any](tuple Tuple9[A, B, C, D, E, F, G, H, I]) (A, B, C, D, E, F, G, H, I)

Unpack9 returns values contained in tuple.

func Unzip2 added in v1.4.0

func Unzip2[A any, B any](tuples []Tuple2[A, B]) ([]A, []B)

Unzip2 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip3 added in v1.4.0

func Unzip3[A any, B any, C any](tuples []Tuple3[A, B, C]) ([]A, []B, []C)

Unzip3 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip4 added in v1.4.0

func Unzip4[A any, B any, C any, D any](tuples []Tuple4[A, B, C, D]) ([]A, []B, []C, []D)

Unzip4 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip5 added in v1.4.0

func Unzip5[A any, B any, C any, D any, E any](tuples []Tuple5[A, B, C, D, E]) ([]A, []B, []C, []D, []E)

Unzip5 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip6 added in v1.4.0

func Unzip6[A any, B any, C any, D any, E any, F any](tuples []Tuple6[A, B, C, D, E, F]) ([]A, []B, []C, []D, []E, []F)

Unzip6 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip7 added in v1.4.0

func Unzip7[A any, B any, C any, D any, E any, F any, G any](tuples []Tuple7[A, B, C, D, E, F, G]) ([]A, []B, []C, []D, []E, []F, []G)

Unzip7 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip8 added in v1.4.0

func Unzip8[A any, B any, C any, D any, E any, F any, G any, H any](tuples []Tuple8[A, B, C, D, E, F, G, H]) ([]A, []B, []C, []D, []E, []F, []G, []H)

Unzip8 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Unzip9 added in v1.4.0

func Unzip9[A any, B any, C any, D any, E any, F any, G any, H any, I any](tuples []Tuple9[A, B, C, D, E, F, G, H, I]) ([]A, []B, []C, []D, []E, []F, []G, []H, []I)

Unzip9 accepts an array of grouped elements and creates an array regrouping the elements to their pre-zip configuration.

func Values

func Values[K comparable, V any](in map[K]V) []V

Values creates an array of the map values.

Types

type Clonable

type Clonable[T any] interface {
	Clone() T
}

Clonable defines a constraint of types having Clone() T method.

type Entry

type Entry[K comparable, V any] struct {
	Key   K
	Value V
}

Entry defines a key/value pairs.

func Entries

func Entries[K comparable, V any](in map[K]V) []Entry[K, V]

Entries transforms a map into array of key/value pairs.

type Tuple2 added in v1.4.0

type Tuple2[A any, B any] struct {
	A A
	B B
}

Tuple2 is a group of 2 elements (pair).

func T2 added in v1.13.0

func T2[A any, B any](a A, b B) Tuple2[A, B]

T2 creates a tuple from a list of values.

func Zip2 added in v1.4.0

func Zip2[A any, B any](a []A, b []B) []Tuple2[A, B]

Zip2 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.

type Tuple3 added in v1.4.0

type Tuple3[A any, B any, C any] struct {
	A A
	B B
	C C
}

Tuple3 is a group of 3 elements.

func T3 added in v1.13.0

func T3[A any, B any, C any](a A, b B, c C) Tuple3[A, B, C]

T3 creates a tuple from a list of values.

func Zip3 added in v1.4.0

func Zip3[A any, B any, C any](a []A, b []B, c []C) []Tuple3[A, B, C]

Zip3 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.

type Tuple4 added in v1.4.0

type Tuple4[A any, B any, C any, D any] struct {
	A A
	B B
	C C
	D D
}

Tuple4 is a group of 4 elements.

func T4 added in v1.13.0

func T4[A any, B any, C any, D any](a A, b B, c C, d D) Tuple4[A, B, C, D]

T4 creates a tuple from a list of values.

func Zip4 added in v1.4.0

func Zip4[A any, B any, C any, D any](a []A, b []B, c []C, d []D) []Tuple4[A, B, C, D]

Zip4 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.

type Tuple5 added in v1.4.0

type Tuple5[A any, B any, C any, D any, E any] struct {
	A A
	B B
	C C
	D D
	E E
}

Tuple5 is a group of 5 elements.

func T5 added in v1.13.0

func T5[A any, B any, C any, D any, E any](a A, b B, c C, d D, e E) Tuple5[A, B, C, D, E]

T5 creates a tuple from a list of values.

func Zip5 added in v1.4.0

func Zip5[A any, B any, C any, D any, E any](a []A, b []B, c []C, d []D, e []E) []Tuple5[A, B, C, D, E]

Zip5 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.

type Tuple6 added in v1.4.0

type Tuple6[A any, B any, C any, D any, E any, F any] struct {
	A A
	B B
	C C
	D D
	E E
	F F
}

Tuple6 is a group of 6 elements.

func T6 added in v1.13.0

func T6[A any, B any, C any, D any, E any, F any](a A, b B, c C, d D, e E, f F) Tuple6[A, B, C, D, E, F]

T6 creates a tuple from a list of values.

func Zip6 added in v1.4.0

func Zip6[A any, B any, C any, D any, E any, F any](a []A, b []B, c []C, d []D, e []E, f []F) []Tuple6[A, B, C, D, E, F]

Zip6 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.

type Tuple7 added in v1.4.0

type Tuple7[A any, B any, C any, D any, E any, F any, G any] struct {
	A A
	B B
	C C
	D D
	E E
	F F
	G G
}

Tuple7 is a group of 7 elements.

func T7 added in v1.13.0

func T7[A any, B any, C any, D any, E any, F any, G any](a A, b B, c C, d D, e E, f F, g G) Tuple7[A, B, C, D, E, F, G]

T7 creates a tuple from a list of values.

func Zip7 added in v1.4.0

func Zip7[A any, B any, C any, D any, E any, F any, G any](a []A, b []B, c []C, d []D, e []E, f []F, g []G) []Tuple7[A, B, C, D, E, F, G]

Zip7 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.

type Tuple8 added in v1.4.0

type Tuple8[A any, B any, C any, D any, E any, F any, G any, H any] struct {
	A A
	B B
	C C
	D D
	E E
	F F
	G G
	H H
}

Tuple8 is a group of 8 elements.

func T8 added in v1.13.0

func T8[A any, B any, C any, D any, E any, F any, G any, H any](a A, b B, c C, d D, e E, f F, g G, h H) Tuple8[A, B, C, D, E, F, G, H]

T8 creates a tuple from a list of values.

func Zip8 added in v1.4.0

func Zip8[A any, B any, C any, D any, E any, F any, G any, H any](a []A, b []B, c []C, d []D, e []E, f []F, g []G, h []H) []Tuple8[A, B, C, D, E, F, G, H]

Zip8 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.

type Tuple9 added in v1.4.0

type Tuple9[A any, B any, C any, D any, E any, F any, G any, H any, I any] struct {
	A A
	B B
	C C
	D D
	E E
	F F
	G G
	H H
	I I
}

Tuple9 is a group of 9 elements.

func T9 added in v1.13.0

func T9[A any, B any, C any, D any, E any, F any, G any, H any, I any](a A, b B, c C, d D, e E, f F, g G, h H, i I) Tuple9[A, B, C, D, E, F, G, H, I]

T8 creates a tuple from a list of values.

func Zip9 added in v1.4.0

func Zip9[A any, B any, C any, D any, E any, F any, G any, H any, I any](a []A, b []B, c []C, d []D, e []E, f []F, g []G, h []H, i []I) []Tuple9[A, B, C, D, E, F, G, H, I]

Zip9 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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL