samber/lo

lo - Iterate over slices, maps, channels...

✨ samber/lo is a Lodash-style Go library based on Go 1.18+ Generics.

A utility library based on Go 1.18+ generics that makes it easier to work with slices, maps, strings, channels, and functions. It provides dozens of handy methods to simplify common coding tasks and improve code readability. It may look like Lodash in some aspects.

5 to 10 helpers may overlap with those from the Go standard library, in packages slices and maps. I feel this library is legitimate and offers many more valuable abstractions.

See also:

• samber/ro: Reactive Programming for Go: declarative and composable API for event-driven applications
• samber/do: A dependency injection toolkit based on Go 1.18+ Generics
• samber/mo: Monads based on Go 1.18+ Generics (Option, Result, Either...)
• samber/cc-skills-golang: AI Agent Skills for Golang

What makes it different from samber/ro?

• lo: synchronous helpers across finite sequences (maps, slices...)
• ro: processing of infinite data streams for event-driven scenarios

Why this name?

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

🚀 Install

go get github.com/samber/lo@v1

# AI Agent Skill
npx skills add https://github.com/samber/cc-skills-golang --skill golang-samber-lo

This library is v1 and follows SemVer strictly.

No breaking changes will be made to exported APIs before v2.0.0, except for experimental packages under exp/.

This library has no dependencies outside the Go standard library.

💡 Usage

You can import lo using:

import (
    "github.com/samber/lo"
    lop "github.com/samber/lo/parallel"
    lom "github.com/samber/lo/mutable"
    loi "github.com/samber/lo/it"
)

Then use one of the helpers below:

names := lo.Uniq([]string{"Samuel", "John", "Samuel"})
// []string{"Samuel", "John"}

Tips for lazy developers

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 for this junk. 😁 💩

🤠 Spec

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

Documentation: lo.samber.dev

Supported helpers for slices:

• Filter
• Map
• UniqMap
• FilterMap
• FlatMap
• Reduce
• ReduceRight
• ForEach
• ForEachWhile
• Times
• Uniq
• UniqBy
• IsUniq
• IsUniqBy
• GroupBy
• GroupByMap
• Chunk
• Window
• Sliding
• PartitionBy
• Flatten
• Concat
• Interleave
• Shuffle
• Reverse
• Fill
• Repeat
• RepeatBy
• KeyBy
• SliceToMap / Associate
• FilterSliceToMap
• Keyify
• Take
• TakeWhile
• TakeFilter
• Drop
• DropRight
• DropWhile
• DropRightWhile
• DropByIndex
• Reject
• RejectMap
• FilterReject
• Count
• CountBy
• CountValues
• CountValuesBy
• Subset
• Slice
• Replace
• ReplaceAll
• Clone
• Compact
• IsSorted
• IsSortedBy
• Splice
• Cut
• CutPrefix
• CutSuffix
• Trim
• TrimLeft
• TrimPrefix
• TrimRight
• TrimSuffix

Supported helpers for maps:

• Keys
• UniqKeys
• HasKey
• ValueOr
• Values
• UniqValues
• PickBy
• PickByKeys
• PickByValues
• OmitBy
• OmitByKeys
• OmitByValues
• Entries / ToPairs
• FromEntries / FromPairs
• Invert
• Assign (merge of maps)
• ChunkEntries
• MapKeys
• MapValues
• MapEntries
• MapToSlice
• FilterMapToSlice
• FilterKeys
• FilterValues

Supported math helpers:

• Range / RangeFrom / RangeWithSteps
• Clamp
• Sum
• SumBy
• Product
• ProductBy
• Mean
• MeanBy
• Mode

Supported helpers for strings:

• RandomString
• Substring
• ChunkString
• RuneLength
• PascalCase
• CamelCase
• KebabCase
• SnakeCase
• Words
• Capitalize
• Ellipsis

Supported helpers for tuples:

• T2 -> T9
• Unpack2 -> Unpack9
• Zip2 -> Zip9
• ZipBy2 -> ZipBy9
• Unzip2 -> Unzip9
• UnzipBy2 -> UnzipBy9
• CrossJoin2 -> CrossJoin2
• CrossJoinBy2 -> CrossJoinBy2

Supported helpers for time and duration:

• Duration
• Duration0 -> Duration10

Supported helpers for channels:

• ChannelDispatcher
• SliceToChannel
• ChannelToSlice
• Generator
• Buffer
• BufferWithContext
• BufferWithTimeout
• FanIn
• FanOut

Supported intersection helpers:

• Contains
• ContainsBy
• Every
• EveryBy
• Some
• SomeBy
• None
• NoneBy
• Intersect
• IntersectBy
• Difference
• Union
• UnionBy
• UnionByErr
• Without
• WithoutBy
• WithoutEmpty
• WithoutNth
• ElementsMatch
• ElementsMatchBy

Supported search helpers:

• IndexOf
• LastIndexOf
• HasPrefix
• HasSuffix
• Find
• FindIndexOf
• FindLastIndexOf
• FindOrElse
• FindKey
• FindKeyBy
• FindUniques
• FindUniquesBy
• FindDuplicates
• FindDuplicatesBy
• Min
• MinIndex
• MinBy
• MinIndexBy
• Earliest
• EarliestBy
• Max
• MaxIndex
• MaxBy
• MaxIndexBy
• Latest
• LatestBy
• First
• FirstOrEmpty
• FirstOr
• Last
• LastOrEmpty
• LastOr
• Nth
• NthOr
• NthOrEmpty
• Sample
• SampleBy
• Samples
• SamplesBy

Conditional helpers:

• Ternary
• TernaryF
• If / ElseIf / Else
• Switch / Case / Default

Type manipulation helpers:

• IsNil
• IsNotNil
• ToPtr
• Nil
• EmptyableToPtr
• FromPtr
• FromPtrOr
• ToSlicePtr
• FromSlicePtr
• FromSlicePtrOr
• ToAnySlice
• FromAnySlice
• Empty
• IsEmpty
• IsNotEmpty
• Coalesce
• CoalesceOrEmpty
• CoalesceSlice
• CoalesceSliceOrEmpty
• CoalesceMap
• CoalesceMapOrEmpty

Function helpers:

• Partial
• Partial2 -> Partial5

Concurrency helpers:

• Attempt
• AttemptWhile
• AttemptWithDelay
• AttemptWhileWithDelay
• Debounce
• DebounceBy
• Throttle
• ThrottleWithCount
• ThrottleBy
• ThrottleByWithCount
• Synchronize
• Async
• Async{0->6}
• Transaction
• WaitFor
• WaitForWithContext

Error handling:

• Validate
• Must
• Try
• Try1 -> Try6
• TryOr
• TryOr1 -> TryOr6
• TryCatch
• TryWithErrorValue
• TryCatchWithErrorValue
• ErrorsAs
• Assert
• Assertf

Constraints:

• Clonable

Filter

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

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

[play]

// Use FilterErr when the predicate can return an error
result, err := lo.FilterErr([]int{1, 2, 3, 4}, func(x int, _ int) (bool, error) {
    if x == 3 {
        return false, fmt.Errorf("number 3 is not allowed")
    }
    return x%2 == 0, nil
})
// []int(nil), error("number 3 is not allowed")

[play]

Mutable: like lo.Filter(), but the slice is updated in place.

import lom "github.com/samber/lo/mutable"

list := []int{1, 2, 3, 4}
newList := lom.Filter(list, func(x int) bool {
    return x%2 == 0
})

list
// []int{2, 4, 3, 4}

newList
// []int{2, 4}

[play]

Map

Manipulates a slice of one type and transforms it into a slice of another type:

import "github.com/samber/lo"

result1:= lo.Map([]int64{1, 2, 3, 4}, func(x int64, index int) string {
    return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}

// Use MapErr when the transform function can return an error
result2, err := lo.MapErr([]int{1, 2, 3, 4}, func(x int, _ int) (string, error) {
    if x == 3 {
        return "", fmt.Errorf("number 3 is not allowed")
    }
    return strconv.Itoa(x), nil
})
// []string(nil), error("number 3 is not allowed")

[play]

Parallel processing: like lo.Map(), but the transform function is called in a goroutine. Results are returned in the same order.

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

partitionedByParity := lop.Map([]int64{1, 2, 3, 4}, func(x int64, _ int) string {
    return strconv.FormatInt(x, 10)
})
// []string{"1", "2", "3", "4"}

[play]

Mutable: like lo.Map(), but the slice is updated in place.

import lom "github.com/samber/lo/mutable"

list := []int{1, 2, 3, 4}
lom.Map(list, func(x int) int {
    return x*2
})
// []int{2, 4, 6, 8}

[play]

UniqMap

Manipulates a slice and transforms it to a slice of another type with unique values.

type User struct {
    Name string
    Age  int
}
users := []User{{Name: "Alex", Age: 10}, {Name: "Alex", Age: 12}, {Name: "Bob", Age: 11}, {Name: "Alice", Age: 20}}

names := lo.UniqMap(users, func(u User, index int) string {
    return u.Name
})
// []string{"Alex", "Bob", "Alice"}

[play]

FilterMap

Returns a slice 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]

FlatMap

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

// Use FlatMapErr when the transform function can return an error
result, err := lo.FlatMapErr([]int64{0, 1, 2, 3}, func(x int64, _ int) ([]string, error) {
    if x == 2 {
        return nil, fmt.Errorf("number 2 is not allowed")
    }
    return []string{strconv.FormatInt(x, 10), strconv.FormatInt(x, 10)}, nil
})
// []string(nil), error("number 2 is not allowed")

[play]

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

// Use ReduceErr when the accumulator function can return an error
result, err := lo.ReduceErr([]int{1, 2, 3, 4}, func(agg int, item int, _ int) (int, error) {
    if item == 3 {
        return 0, fmt.Errorf("number 3 is not allowed")
    }
    return agg + item, nil
}, 0)
// 0, error("number 3 is not allowed")

[play]

ReduceRight

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}

// Use ReduceRightErr when the accumulator function can return an error
result, err := lo.ReduceRightErr([]int{1, 2, 3, 4}, func(agg int, item int, _ int) (int, error) {
    if item == 2 {
        return 0, fmt.Errorf("number 2 is not allowed")
    }
    return agg + item, nil
}, 0)
// 0, error("number 2 is not allowed")

[play]

ForEach

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"

ForEachWhile

Iterates over collection elements and invokes iteratee for each element collection return value decide to continue or break, like do while().

list := []int64{1, 2, -42, 4}

lo.ForEachWhile(list, func(x int64, _ int) bool {
	if x < 0 {
		return false
	}
	fmt.Println(x)
	return true
})
// 1
// 2

[play]

Times

Times invokes the iteratee n times, returning a slice 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"}

Uniq

Returns a duplicate-free version of a slice, 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 slice.

uniqValues := lo.Uniq([]int{1, 2, 2, 1})
// []int{1, 2}

[play]

UniqBy

Returns a duplicate-free version of a slice, 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 slice. It accepts iteratee which is invoked for each element in the slice 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}

// Use UniqByErr when the iteratee function can return an error
result, err := lo.UniqByErr([]int{0, 1, 2, 3, 4, 5}, func(i int) (int, error) {
    if i == 3 {
        return 0, fmt.Errorf("number 3 is not allowed")
    }
    return i % 3, nil
})
// []int(nil), error("number 3 is not allowed")

[play]

IsUniq

Returns true if all elements in the slice are unique, false otherwise. Returns true for nil and empty slices.

lo.IsUniq([]int{1, 2, 3})
// true

lo.IsUniq([]int{1, 2, 1})
// false

IsUniqBy

Returns true if all elements in the slice are unique based on a custom criterion. It accepts iteratee which is invoked for each element in the slice to generate the criterion by which uniqueness is computed. Returns true for nil and empty slices.

type User struct {
    ID   int
    Name string
}

users := []User{{ID: 1, Name: "Alice"}, {ID: 2, Name: "Bob"}, {ID: 1, Name: "Charlie"}}

lo.IsUniqBy(users, func(u User) int { return u.ID })
// false

lo.IsUniqBy(users, func(u User) string { return u.Name })
// true

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

// Use GroupByErr when the iteratee function can return an error
result, err := lo.GroupByErr([]int{0, 1, 2, 3, 4, 5}, func(i int) (int, error) {
    if i == 3 {
        return 0, fmt.Errorf("number 3 is not allowed")
    }
    return i % 3, nil
})
// map[int][]int(nil), error("number 3 is not allowed")

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

GroupByMap

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.GroupByMap([]int{0, 1, 2, 3, 4, 5}, func(i int) (int, int) {
    return i%3, i*2
})
// map[int][]int{0: []int{0, 6}, 1: []int{2, 8}, 2: []int{4, 10}}

// Use GroupByMapErr when the transform function can return an error
result, err := lo.GroupByMapErr([]int{0, 1, 2, 3, 4, 5}, func(i int) (int, int, error) {
    if i == 3 {
        return 0, 0, fmt.Errorf("number 3 is not allowed")
    }
    return i % 3, i * 2, nil
})
// map[int][]int(nil), error("number 3 is not allowed")

[play]

Chunk

Returns a slice of elements split into groups of length size. If the slice 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]

Window

Creates a slice of sliding windows of a given size. Each window shares size-1 elements with the previous one. This is equivalent to Sliding(collection, size, 1).

lo.Window([]int{1, 2, 3, 4, 5}, 3)
// [][]int{{1, 2, 3}, {2, 3, 4}, {3, 4, 5}}

lo.Window([]float64{20, 22, 21, 23, 24}, 3)
// [][]float64{{20, 22, 21}, {22, 21, 23}, {21, 23, 24}}

[play]

Sliding

Creates a slice of sliding windows of a given size with a given step. If step is equal to size, windows have no common elements (similar to Chunk). If step is less than size, windows share common elements.

// Windows with shared elements (step < size)
lo.Sliding([]int{1, 2, 3, 4, 5, 6}, 3, 1)
// [][]int{{1, 2, 3}, {2, 3, 4}, {3, 4, 5}, {4, 5, 6}}

// Windows with no shared elements (step == size, like Chunk)
lo.Sliding([]int{1, 2, 3, 4, 5, 6}, 3, 3)
// [][]int{{1, 2, 3}, {4, 5, 6}}

// Step > size (skipping elements)
lo.Sliding([]int{1, 2, 3, 4, 5, 6, 7, 8}, 2, 3)
// [][]int{{1, 2}, {4, 5}, {7, 8}}

[play]

PartitionBy

Returns a slice 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}}

// Use PartitionByErr when the iteratee function can return an error
result, err := lo.PartitionByErr([]int{-2, -1, 0, 1, 2}, func(x int) (string, error) {
    if x == 0 {
        return "", fmt.Errorf("zero is not allowed")
    }
    if x < 0 {
        return "negative", nil
    } else if x%2 == 0 {
        return "even", nil
    }
    return "odd", nil
})
// [][]int(nil), error("zero is not allowed")

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

Flatten

Returns a slice a single level deep.

flat := lo.Flatten([][]int{{0, 1}, {2, 3, 4, 5}})
// []int{0, 1, 2, 3, 4, 5}

[play]

Concat

Returns a new slice containing all the elements in collections. Concat conserves the order of the elements.

slice := lo.Concat([]int{1, 2}, []int{3, 4})
// []int{1, 2, 3, 4}

slice := lo.Concat(nil, []int{1, 2}, nil, []int{3, 4}, nil)
// []int{1, 2, 3, 4}

slice := lo.Concat[int]()
// []int{}

Interleave

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]

Shuffle

Returns a slice of shuffled values. Uses the Fisher-Yates shuffle algorithm.

⚠️ This helper is mutable.

import lom "github.com/samber/lo/mutable"

list := []int{0, 1, 2, 3, 4, 5}
lom.Shuffle(list)

list
// []int{1, 4, 0, 3, 5, 2}

[play]

Reverse

Reverses a slice so that the first element becomes the last, the second element becomes the second to last, and so on.

⚠️ This helper is mutable.

import lom "github.com/samber/lo/mutable"

list := []int{0, 1, 2, 3, 4, 5}
lom.Reverse(list)

list
// []int{5, 4, 3, 2, 1, 0}

[play]

Fill

Fills elements of a slice 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]

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

[play]

RepeatBy

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]

With error handling:

slice, err := lo.RepeatByErr(5, func(i int) (string, error) {
    if i == 3 {
        return "", fmt.Errorf("index 3 is not allowed")
    }
    return fmt.Sprintf("item-%d", i), nil
})
// []string(nil), error("index 3 is not allowed")

KeyBy

Transforms a slice or a slice 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}]

result, err := lo.KeyByErr([]string{"a", "aa", "aaa", ""}, func(str string) (int, error) {
    if str == "" {
        return 0, fmt.Errorf("empty string not allowed")
    }
    return len(str), nil
})
// map[int]string(nil), error("empty string not allowed")

[play]

SliceToMap (alias: Associate)

Returns a map containing key-value pairs provided by transform function applied to elements of the given slice. If any of two pairs 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 slice.

in := []*foo{{baz: "apple", bar: 1}, {baz: "banana", bar: 2}}

aMap := lo.SliceToMap(in, func (f *foo) (string, int) {
    return f.baz, f.bar
})
// map[string][int]{ "apple":1, "banana":2 }

[play]

FilterSliceToMap

Returns a map containing key-value pairs provided by transform function applied to elements of the given slice.

If any of two pairs 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 slice.

The third return value of the transform function is a boolean that indicates whether the key-value pair should be included in the map.

list := []string{"a", "aa", "aaa"}

result := lo.FilterSliceToMap(list, func(str string) (string, int, bool) {
    return str, len(str), len(str) > 1
})
// map[string][int]{"aa":2 "aaa":3}

[play]

Keyify

Returns a map with each unique element of the slice as a key.

set := lo.Keyify([]int{1, 1, 2, 3, 4})
// map[int]struct{}{1:{}, 2:{}, 3:{}, 4:{}}

[play]

Take

Takes the first n elements from a slice.

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

l := lo.Take([]int{0, 1, 2}, 5)
// []int{0, 1, 2}

[play]

TakeWhile

Takes elements from the beginning while the predicate returns true.

l := lo.TakeWhile([]int{0, 1, 2, 3, 4, 5}, func(val int) bool {
    return val < 3
})
// []int{0, 1, 2}

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

[play]

TakeFilter

Filters elements and takes the first n elements that match the predicate. Equivalent to calling Take(Filter(...)), but more efficient as it stops after finding n matches.

l := lo.TakeFilter([]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, 3, func(val int, index int) bool {
    return val%2 == 0
})
// []int{2, 4, 6}

l := lo.TakeFilter([]string{"a", "aa", "aaa", "aaaa"}, 2, func(val string, index int) bool {
    return len(val) > 1
})
// []string{"aa", "aaa"}

[play]

Drop

Drops n elements from the beginning of a slice.

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

[play]

DropRight

Drops n elements from the end of a slice.

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

[play]

DropWhile

Drop elements from the beginning of a slice 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]

DropRightWhile

Drop elements from the end of a slice 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]

DropByIndex

Drops elements from a slice by the index. A negative index will drop elements from the end of the slice.

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

[play]

Reject

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

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

// Use RejectErr when the predicate can return an error
odd, err := lo.RejectErr([]int{1, 2, 3, 4}, func(x int, _ int) (bool, error) {
    if x == 3 {
        return false, fmt.Errorf("number 3 is not allowed")
    }
    return x%2 == 0, nil
})
// []int(nil), error("number 3 is not allowed")

[play]

RejectMap

The opposite of FilterMap, this method returns a slice 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.

items := lo.RejectMap([]int{1, 2, 3, 4}, func(x int, _ int) (int, bool) {
    return x*10, x%2 == 0
})
// []int{10, 30}

[play]

FilterReject

Mixes Filter and Reject, this method returns two slices, one for the elements of collection that predicate returns true for and one for the elements that predicate does not return true for.

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

[play]

Count

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

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

[play]

CountBy

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

// Use CountByErr when the predicate can return an error
count, err := lo.CountByErr([]int{1, 5, 1}, func(i int) (bool, error) {
    if i == 5 {
        return false, fmt.Errorf("5 not allowed")
    }
    return i < 4, nil
})
// 0, error("5 not allowed")

[play]

CountValues

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]

CountValuesBy

Counts the number of each element in the collection. It is 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]

Subset

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]

Slice

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]

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}

[play]

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}

[play]

Clone

Returns a shallow copy of the collection.

in := []int{1, 2, 3, 4, 5}
cloned := lo.Clone(in)
// Verify it's a different slice by checking that modifying one doesn't affect the other
in[0] = 99
// cloned is []int{1, 2, 3, 4, 5}

[play]

Compact

Returns a slice of all non-zero elements.

in := []string{"", "foo", "", "bar", ""}

slice := lo.Compact(in)
// []string{"foo", "bar"}

[play]

IsSorted

Checks if a slice is sorted.

slice := lo.IsSorted([]int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9})
// true

[play]

IsSortedBy

Checks if a slice is sorted by iteratee.

slice := lo.IsSortedBy([]string{"a", "bb", "ccc"}, func(s string) int {
    return len(s)
})
// true

[play]

Splice

Splice inserts multiple elements at index i. A negative index counts back from the end of the slice. The helper is protected against overflow errors.

result := lo.Splice([]string{"a", "b"}, 1, "1", "2")
// []string{"a", "1", "2", "b"}

// negative
result = lo.Splice([]string{"a", "b"}, -1, "1", "2")
// []string{"a", "1", "2", "b"}

// overflow
result = lo.Splice([]string{"a", "b"}, 42, "1", "2")
// []string{"a", "b", "1", "2"}

[play]

Cut

Slices collection around the first instance of separator, returning the part of collection before and after separator. The found result reports whether separator appears in collection. If separator does not appear in s, cut returns collection, empty slice of []T, false.

actualLeft, actualRight, result = lo.Cut([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"b", "c", "d"})
// actualLeft: []string{"a"}
// actualRight: []string{"e", "f", "g"}
// result: true

result = lo.Cut([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"z"})
// actualLeft: []string{"a", "b", "c", "d", "e", "f", "g"}
// actualRight: []string{}
// result: false

result = lo.Cut([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"a", "b"})
// actualLeft: []string{}
// actualRight: []string{"c", "d", "e", "f", "g"}
// result: true

[play]

CutPrefix

Returns collection without the provided leading prefix []T and reports whether it found the prefix. If s doesn't start with prefix, CutPrefix returns collection, false. If prefix is the empty []T, CutPrefix returns collection, true.

actualRight, result = lo.CutPrefix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"a", "b", "c"})
// actualRight: []string{"d", "e", "f", "g"}
// result: true

result = lo.CutPrefix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"b"})
// actualRight: []string{"a", "b", "c", "d", "e", "f", "g"}
// result: false

result = lo.CutPrefix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{})
// actualRight: []string{"a", "b", "c", "d", "e", "f", "g"}
// result: true

[play]

CutSuffix

Returns collection without the provided ending suffix []T and reports whether it found the suffix. If it doesn't end with suffix, CutSuffix returns collection, false. If suffix is the empty []T, CutSuffix returns collection, true.

actualLeft, result = lo.CutSuffix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"f", "g"})
// actualLeft: []string{"a", "b", "c", "d", "e"}
// result: true

actualLeft, result = lo.CutSuffix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{"b"})
// actualLeft: []string{"a", "b", "c", "d", "e", "f", "g"}
// result: false

actualLeft, result = lo.CutSuffix([]string{"a", "b", "c", "d", "e", "f", "g"}, []string{})
// actualLeft: []string{"a", "b", "c", "d", "e", "f", "g"}
// result: true

[play]

Trim

Removes all the leading and trailing cutset from the collection.

result := lo.Trim([]int{0, 1, 2, 0, 3, 0}, []int{1, 0})
// []int{2, 0, 3}

result := lo.Trim([]string{"hello", "world", " "}, []string{" ", ""})
// []string{"hello", "world"}

[play]

TrimLeft

Removes all the leading cutset from the collection.

result := lo.TrimLeft([]int{0, 1, 2, 0, 3, 0}, []int{1, 0})
// []int{2, 0, 3, 0}

result := lo.TrimLeft([]string{"hello", "world", " "}, []string{" ", ""})
// []string{"hello", "world", " "}

[play]

TrimPrefix

Removes all the leading prefix from the collection.

result := lo.TrimPrefix([]int{1, 2, 1, 2, 3, 1, 2, 4}, []int{1, 2})
// []int{3, 1, 2, 4}

result := lo.TrimPrefix([]string{"hello", "world", "hello", "test"}, []string{"hello"})
// []string{"world", "hello", "test"}

[play]

TrimRight

Removes all the trailing cutset from the collection.

result := lo.TrimRight([]int{0, 1, 2, 0, 3, 0}, []int{0, 3})
// []int{0, 1, 2}

result := lo.TrimRight([]string{"hello", "world", "  "}, []string{" ", ""})
// []string{"hello", "world", ""}

[play]

TrimSuffix

Removes all the trailing suffix from the collection.

result := lo.TrimSuffix([]int{1, 2, 3, 1, 2, 4, 2, 4, 2, 4}, []int{2, 4})
// []int{1, 2, 3, 1}

result := lo.TrimSuffix([]string{"hello", "world", "hello", "test"}, []string{"test"})
// []string{"hello", "world", "hello"}

[play]

Keys

Creates a slice of the map keys.

Use the UniqKeys variant to deduplicate common keys.

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

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

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

[play]

UniqKeys

Creates a slice of unique map keys.

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

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

[play]

HasKey

Returns whether the given key exists.

exists := lo.HasKey(map[string]int{"foo": 1, "bar": 2}, "foo")
// true

exists := lo.HasKey(map[string]int{"foo": 1, "bar": 2}, "baz")
// false

[play]

Values

Creates a slice of the map values.

Use the UniqValues variant to deduplicate common values.

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

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

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

[play]

UniqValues

Creates a slice of unique map values.

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

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

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

[play]

ValueOr

Returns the value of the given key or the fallback value if the key is not present.

value := lo.ValueOr(map[string]int{"foo": 1, "bar": 2}, "foo", 42)
// 1

value := lo.ValueOr(map[string]int{"foo": 1, "bar": 2}, "baz", 42)
// 42

[play]

PickBy

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}

// Use PickByErr when the predicate can return an error
m, err := lo.PickByErr(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(key string, value int) (bool, error) {
    if key == "bar" {
        return false, fmt.Errorf("bar not allowed")
    }
    return value%2 == 1, nil
})
// map[string]int(nil), error("bar not allowed")

[play]

PickByKeys

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]

PickByValues

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]

OmitBy

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}

// Use OmitByErr when the predicate can return an error
m, err := lo.OmitByErr(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(key string, value int) (bool, error) {
    if key == "bar" {
        return false, fmt.Errorf("bar not allowed")
    }
    return value%2 == 1, nil
})
// map[string]int(nil), error("bar not allowed")

[play]

OmitByKeys

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]

OmitByValues

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]

Entries (alias: ToPairs)

Transforms a map into a slice 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]

FromEntries (alias: FromPairs)

Transforms a slice 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]

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

Assign

Merges multiple maps from left to right.

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

[play]

ChunkEntries

Splits a map into a slice of elements in groups of length equal to its size. If the map cannot be split evenly, the final chunk will contain the remaining elements.

maps := lo.ChunkEntries(
    map[string]int{
        "a": 1,
        "b": 2,
        "c": 3,
        "d": 4,
        "e": 5,
    },
    3,
)
// []map[string]int{
//    {"a": 1, "b": 2, "c": 3},
//    {"d": 4, "e": 5},
// }

[play]

MapKeys

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

// Use MapKeysErr when the iteratee can return an error
m2, err := lo.MapKeysErr(map[int]int{1: 1, 2: 2, 3: 3}, func(_ int, v int) (string, error) {
    if v == 2 {
        return "", fmt.Errorf("even number not allowed")
    }
    return strconv.FormatInt(int64(v), 10), nil
})
// map[string]int(nil), error("even number not allowed")

[play]

MapValues

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

// Use MapValuesErr when the iteratee can return an error
m1 := map[int]int64{1: 1, 2: 2, 3: 3}
m2, err := lo.MapValuesErr(m1, func(x int64, _ int) (string, error) {
    if x == 2 {
        return "", fmt.Errorf("even number not allowed")
    }
    return strconv.FormatInt(x, 10), nil
})
// map[int]string(nil), error("even number not allowed")

[play]

MapEntries

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

// Use MapEntriesErr when the iteratee can return an error
in := map[string]int{"foo": 1, "bar": 2, "baz": 3}
out, err := lo.MapEntriesErr(in, func(k string, v int) (int, string, error) {
    if k == "bar" {
        return 0, "", fmt.Errorf("bar not allowed")
    }
    return v, k, nil
})
// map[int]string(nil), error("bar not allowed")

[play]

MapToSlice

Transforms a map into a slice based on specified 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"}

// Use MapToSliceErr when the iteratee can return an error
m := map[int]int64{1: 4, 2: 5, 3: 6}
s, err := lo.MapToSliceErr(m, func(k int, v int64) (string, error) {
    if k == 2 {
        return "", fmt.Errorf("key 2 not allowed")
    }
    return fmt.Sprintf("%d_%d", k, v), nil
})
// []string(nil), error("key 2 not allowed")

[play]

FilterMapToSlice

Transforms a map into a slice based on specified iteratee. The iteratee returns a value and a boolean. If the boolean is true, the value is added to the result slice.

If the boolean is false, the value is not added to the result slice. The order of the keys in the input map is not specified and the order of the keys in the output slice is not guaranteed.

kv := map[int]int64{1: 1, 2: 2, 3: 3, 4: 4}

result := lo.FilterMapToSlice(kv, func(k int, v int64) (string, bool) {
    return fmt.Sprintf("%d_%d", k, v), k%2 == 0
})
// []{"2_2", "4_4"}

[play]

kv := map[int]int64{1: 1, 2: 2, 3: 3, 4: 4}

result, err := lo.FilterMapToSliceErr(kv, func(k int, v int64) (string, bool, error) {
    if k == 3 {
        return "", false, fmt.Errorf("key 3 not allowed")
    }
    return fmt.Sprintf("%d_%d", k, v), k%2 == 0, nil
})
// []string(nil), error("key 3 not allowed")

[play]

FilterKeys

Transforms a map into a slice based on predicate returns true for specific elements. It is a mix of lo.Filter() and lo.Keys().

kv := map[int]string{1: "foo", 2: "bar", 3: "baz"}

result := FilterKeys(kv, func(k int, v string) bool {
    return v == "foo"
})
// [1]

[play]

// Use FilterKeysErr when the predicate can return an error
result, err := lo.FilterKeysErr(map[int]string{1: "foo", 2: "bar", 3: "baz"}, func(k int, v string) (bool, error) {
    if k == 3 {
        return false, fmt.Errorf("key 3 not allowed")
    }
    return v == "foo", nil
})
// []int(nil), error("key 3 not allowed")

[play]

FilterValues

Transforms a map into a slice based on predicate returns true for specific elements. It is a mix of lo.Filter() and lo.Values().

kv := map[int]string{1: "foo", 2: "bar", 3: "baz"}

result := FilterValues(kv, func(k int, v string) bool {
    return v == "foo"
})
// ["foo"]

[play]

// Use FilterValuesErr when the predicate can return an error
result, err := lo.FilterValuesErr(map[int]string{1: "foo", 2: "bar", 3: "baz"}, func(k int, v string) (bool, error) {
    if k == 3 {
        return false, fmt.Errorf("key 3 not allowed")
    }
    return v == "foo", nil
})
// []string(nil), error("key 3 not allowed")

[play]

Range / RangeFrom / RangeWithSteps

Creates a slice 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]

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

[play]

Sum

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]

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

[play]

With error handling:

strings := []string{"foo", "bar", "baz"}
sum, err := lo.SumByErr(strings, func(item string) (int, error) {
    if item == "bar" {
        return 0, fmt.Errorf("invalid item: %s", item)
    }
    return len(item), nil
})
// sum: 3, err: invalid item: bar

[play]

Product

Calculates the product of the values in a collection.

If collection is empty 0 is returned.

list := []int{1, 2, 3, 4, 5}
product := lo.Product(list)
// 120

[play]

ProductBy

Calculates the product of 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"}
product := lo.ProductBy(strings, func(item string) int {
    return len(item)
})
// 9

// Use ProductByErr when the transform function can return an error
strings := []string{"foo", "bar", "baz"}
product, err := lo.ProductByErr(strings, func(item string) (int, error) {
    if item == "bar" {
        return 0, fmt.Errorf("bar is not allowed")
    }
    return len(item), nil
})
// 3, error("bar is not allowed")

[play]

Mean

Calculates the mean of a collection of numbers.

If collection is empty 0 is returned.

mean := lo.Mean([]int{2, 3, 4, 5})
// 3

mean := lo.Mean([]float64{2, 3, 4, 5})
// 3.5

mean := lo.Mean([]float64{})
// 0

[play]

MeanBy

Calculates the mean of a collection of numbers using the given return value from the iteration function.

If collection is empty 0 is returned.

list := []string{"aa", "bbb", "cccc", "ddddd"}
mapper := func(item string) float64 {
    return float64(len(item))
}

mean := lo.MeanBy(list, mapper)
// 3.5

mean := lo.MeanBy([]string{}, mapper)
// 0

[play]

// Use MeanByErr when the transform function can return an error
list := []string{"aa", "bbb", "cccc", "ddddd"}
mean, err := lo.MeanByErr(list, func(item string) (float64, error) {
    if item == "cccc" {
        return 0, fmt.Errorf("cccc is not allowed")
    }
    return float64(len(item)), nil
})
// 0, error("cccc is not allowed")

[play]

Mode

Calculates the mode (most frequent value) of a collection of numbers.

If multiple values have the same highest frequency, then multiple values are returned.

If the collection is empty, the zero value of T[] is returned.

mode := lo.Mode([]int{2, 2, 3, 4})
// [2]

mode := lo.Mode([]float64{2, 2, 3, 3})
// [2, 3]

mode := lo.Mode([]float64{})
// []

mode := lo.Mode([]int{1, 2, 3, 4, 5, 6, 7, 8, 9})
// [1, 2, 3, 4, 5, 6, 7, 8, 9]

[play]

RandomString

Returns a random string of the specified length and made of the specified charset.

str := lo.RandomString(5, lo.LettersCharset)
// example: "eIGbt"

[play]

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"

[play]

ChunkString

Returns a slice of strings split into groups of length size. If the string can't be split evenly, the final chunk will be the remaining characters.

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

Note: lo.ChunkString and lo.Chunk functions behave inconsistently for empty input: lo.ChunkString("", n) returns [""] instead of []. See #788.

[play]

RuneLength

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

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

sub := len("hellô")
// 6

[play]

PascalCase

Converts string to pascal case.

str := lo.PascalCase("hello_world")
// HelloWorld

[play]

CamelCase

Converts string to camel case.

str := lo.CamelCase("hello_world")
// helloWorld

[play]

KebabCase

Converts string to kebab case.

str := lo.KebabCase("helloWorld")
// hello-world

[play]

SnakeCase

Converts string to snake case.

str := lo.SnakeCase("HelloWorld")
// hello_world

[play]

Words

Splits string into a slice of its words.

str := lo.Words("helloWorld")
// []string{"hello", "world"}

[play]

Capitalize

Converts the first character of string to upper case and the remaining to lower case.

str := lo.Capitalize("heLLO")
// Hello

[play]

Ellipsis

Trims and truncates a string to a specified length in runes (Unicode code points) and appends an ellipsis if truncated. Multi-byte characters such as emoji or CJK ideographs are never split in the middle.

str := lo.Ellipsis("  Lorem Ipsum  ", 5)
// Lo...

str := lo.Ellipsis("Lorem Ipsum", 100)
// Lorem Ipsum

str := lo.Ellipsis("Lorem Ipsum", 3)
// ...

str := lo.Ellipsis("hello 世界! 你好", 8)
// hello...

str := lo.Ellipsis("🏠🐶🐱🌟", 4)
// 🏠🐶🐱🌟

[play]

T2 -> T9

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]

Unpack2 -> Unpack9

Returns values contained in a tuple.

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

Unpack is also available as a method of TupleX.

tuple2 := lo.T2("a", 1)
a, b := tuple2.Unpack()
// "a", 1

[play]

Zip2 -> Zip9

Zip creates a slice of grouped elements, the first of which contains the first elements of the given slices, the second of which contains the second elements of the given slices, and so on.

When collections are different sizes, 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]

ZipBy2 -> ZipBy9

ZipBy creates a slice of transformed elements, the first of which contains the first elements of the given slices, the second of which contains the second elements of the given slices, and so on.

When collections are different sizes, the Tuple attributes are filled with zero value.

items := lo.ZipBy2([]string{"a", "b"}, []int{1, 2}, func(a string, b int) string {
    return fmt.Sprintf("%s-%d", a, b)
})
// []string{"a-1", "b-2"}

[play]

With error handling:

items, err := lo.ZipByErr2([]string{"a", "b"}, []int{1, 2}, func(a string, b int) (string, error) {
    if b == 2 {
        return "", fmt.Errorf("number 2 is not allowed")
    }
    return fmt.Sprintf("%s-%d", a, b), nil
})
// []string(nil), error("number 2 is not allowed")

[play]

Unzip2 -> Unzip9

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

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

[play]

UnzipBy2 -> UnzipBy9

UnzipBy2 iterates over a collection and creates a slice regrouping the elements to their pre-zip configuration.

a, b := lo.UnzipBy2([]string{"hello", "john", "doe"}, func(str string) (string, int) {
    return str, len(str)
})
// []string{"hello", "john", "doe"}
// []int{5, 4, 3}

[play]

a, b, err := lo.UnzipByErr2([]string{"hello", "error", "world"}, func(str string) (string, int, error) {
    if str == "error" {
        return "", 0, fmt.Errorf("error string not allowed")
    }
    return str, len(str), nil
})
// []string{}
// []int{}
// error string not allowed

[play]

CrossJoin2 -> CrossJoin9

Combines every item from one list with every item from others. It is the cartesian product of lists received as arguments. Returns an empty list if a list is empty.

result := lo.CrossJoin2([]string{"hello", "john", "doe"}, []int{1, 2})
// lo.Tuple2{"hello", 1}
// lo.Tuple2{"hello", 2}
// lo.Tuple2{"john", 1}
// lo.Tuple2{"john", 2}
// lo.Tuple2{"doe", 1}
// lo.Tuple2{"doe", 2}

[play]

CrossJoinBy2 -> CrossJoinBy9

Combines every item from one list with every item from others. It is the cartesian product of lists received as arguments. The transform function is used to create the output values. Returns an empty list if a list is empty.

result := lo.CrossJoinBy2([]string{"hello", "john", "doe"}, []int{1, 2}, func(a string, b int) string {
    return fmt.Sprintf("%s - %d", a, b)
})
// "hello - 1"
// "hello - 2"
// "john - 1"
// "john - 2"
// "doe - 1"
// "doe - 2"

[play]

With error handling:

result, err := lo.CrossJoinByErr2([]string{"hello", "john"}, []int{1, 2}, func(a string, b int) (string, error) {
    if a == "john" {
        return "", fmt.Errorf("john not allowed")
    }
    return fmt.Sprintf("%s - %d", a, b), nil
})
// []string(nil), error("john not allowed")

[play]

Duration

Returns the time taken to execute a function.

duration := lo.Duration(func() {
    // very long job
})
// 3s

[play]

Duration0 -> Duration10

Returns the time taken to execute a function.

duration := lo.Duration0(func() {
    // very long job
})
// 3s

err, duration := lo.Duration1(func() error {
    // very long job
    return errors.New("an error")
})
// an error
// 3s

str, nbr, err, duration := lo.Duration3(func() (string, int, error) {
    // very long job
    return "hello", 42, nil
})
// hello
// 42
// nil
// 3s

[play]

ChannelDispatcher

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])
}

[play]

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

Eg:

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

SliceToChannel

Returns a read-only channel 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) {
    fmt.Println(v)
}
// 1
// 2
// 3
// 4
// 5

[play]

ChannelToSlice

Returns a slice built from channel 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}

Generator

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 3

Buffer

Creates 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, false

[play]

Example: RabbitMQ consumer 👇

ch := readFromQueue()

for {
    // read 1k items
    items, length, _, ok := lo.Buffer(ch, 1000)

    // do batching stuff

    if !ok {
        break
    }
}

BufferWithContext

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

ctx, cancel := context.WithCancel(context.TODO())
go func() {
    ch <- 0
    time.Sleep(10*time.Millisecond)
    ch <- 1
    time.Sleep(10*time.Millisecond)
    ch <- 2
    time.Sleep(10*time.Millisecond)
    ch <- 3
    time.Sleep(10*time.Millisecond)
    ch <- 4
    time.Sleep(10*time.Millisecond)
    cancel()
}()

items1, length1, duration1, ok1 := lo.BufferWithContext(ctx, ch, 3)
// []int{0, 1, 2}, 3, 20ms, true
items2, length2, duration2, ok2 := lo.BufferWithContext(ctx, ch, 3)
// []int{3, 4}, 2, 30ms, false

BufferWithTimeout

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{0, 1, 2}, 3, 70ms, true
items2, length2, duration2, ok2 := lo.BufferWithTimeout(ch, 3, 100*time.Millisecond)
// []int{3, 4}, 2, 100ms, true
items3, length3, duration2, ok3 := lo.BufferWithTimeout(ch, 3, 100*time.Millisecond)
// []int{}, 0, 5ms, false

[play]

Example: 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])
}

FanIn

Merge messages from multiple input channels into a single buffered channel. Output messages have 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)

stream1 <- 1
stream1 <- 2

stream2 <- 3

stream3 <- 4
stream3 <- 5
stream3 <- 6

all := lo.FanIn(100, stream1, stream2, stream3)

close(stream1)
close(stream2)
close(stream3)

for value := range all {
    fmt.Println(value)
}
// prints 1, 2, 3, 4, 5 and 6, in no particular order

[play]

FanOut

Broadcasts all the upstream messages to multiple downstream channels. When upstream channel reaches 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 int

Contains

Returns true if an element is present in a collection.

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

[play]

ContainsBy

Returns true if the predicate function returns true.

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

[play]

Every

Returns true if all elements of a subset are contained in 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})
// false

[play]

EveryBy

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

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

[play]

Some

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

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

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

[play]

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

None

Returns true if no element of a subset is contained in 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})
// true

[play]

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

[play]

Intersect

Returns the intersection between 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{}

result4 := lo.Intersect([]int{0, 3, 5, 7}, []int{3, 5}, []int{0, 1, 2, 0, 3, 0})
// []int{3}

IntersectBy

Returns the intersection between two collections using a custom key selector function.

transform := func(v int) string {
    return strconv.Itoa(v)
}

result1 := lo.IntersectBy(transform, []int{0, 1, 2, 3, 4, 5}, []int{0, 2})
// []int{0, 2}

result2 := lo.IntersectBy(transform, []int{0, 1, 2, 3, 4, 5}, []int{0, 6})
// []int{0}

result3 := lo.IntersectBy(transform, []int{0, 1, 2, 3, 4, 5}, []int{-1, 6})
// []int{}

result4 := lo.IntersectBy(transform, []int{0, 3, 5, 7}, []int{3, 5}, []int{0, 1, 2, 0, 3, 0})
// []int{3}

Difference

Returns the difference between two collections.

• The first value is the collection of elements absent from list2.
• The second value is the collection of elements absent from 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{}

[play]

Union

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}

UnionBy

Returns all distinct elements from given collections based on an iteratee function. Result will not change the order of elements relatively.

predicate := func(i int) int {
    return i / 2
}
union := lo.UnionBy(predicate, []int{0, 1, 2, 3, 4, 5}, []int{0, 2, 10}, []int{0, 1, 11})
// []int{0, 2, 4, 10}

UnionByErr

Returns all distinct elements from given collections based on an iteratee function. Result will not change the order of elements relatively. It returns the first error returned by the iteratee.

predicate := func(i int) (int, error) {
    if i == 42 {
        return 0, errors.New("invalid value")
    }
    return i / 2, nil
}
union, err := lo.UnionByErr(predicate, []int{0, 1, 2, 3, 4, 5}, []int{0, 2, 10}, []int{0, 1, 11})
// union: []int{0, 2, 4, 10}
// err: nil

Without

Returns a 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}

WithoutBy

Filters a slice by excluding elements whose extracted keys match any in the exclude list.

Returns a new slice containing only the elements whose keys are not in the exclude list.

type User struct {
    ID int
    Name string
}

// original users
users := []User{
    {ID: 1, Name: "Alice"},
    {ID: 2, Name: "Bob"},
    {ID: 3, Name: "Charlie"},
}

// extract function to get the user ID
getID := func(user User) int {
    return user.ID
}

// exclude users with IDs 2 and 3
excludedIDs := []int{2, 3}

// filtering users
filteredUsers := lo.WithoutBy(users, getID, excludedIDs...)
// []User[{ID: 1, Name: "Alice"}]

// Use WithoutByErr when the iteratee can return an error
type struct User {
    ID int
    Name string
}

users := []User{
    {ID: 1, Name: "Alice"},
    {ID: 2, Name: "Bob"},
    {ID: 3, Name: "Charlie"},
}

getID := func(user User) (int, error) {
    if user.ID == 2 {
        return 0, fmt.Errorf("Bob not allowed")
    }
    return user.ID, nil
}

filteredUsers, err := lo.WithoutByErr(users, getID, 2, 3)
// []User(nil), error("Bob not allowed")

WithoutEmpty

Returns a slice excluding zero values.

subset := lo.WithoutEmpty([]int{0, 2, 10})
// []int{2, 10}

WithoutNth

Returns a slice excluding the nth value.

subset := lo.WithoutNth([]int{-2, -1, 0, 1, 2}, 3, -42, 1)
// []int{-2, 0, 2}

ElementsMatch

Returns true if lists contain the same set of elements (including empty set).

If there are duplicate elements, the number of occurrences in each list should match.

The order of elements is not checked.

b := lo.ElementsMatch([]int{1, 1, 2}, []int{2, 1, 1})
// true

ElementsMatchBy

Returns true if lists contain the same set of elements' keys (including empty set).

If there are duplicate keys, the number of occurrences in each list should match.

The order of elements is not checked.

b := lo.ElementsMatchBy(
    []someType{a, b},
    []someType{b, a},
    func(item someType) string { return item.ID() },
)
// true

IndexOf

Returns the index at which the first occurrence of a value is found in a slice or -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)
// -1

[play]

LastIndexOf

Returns the index at which the last occurrence of a value is found in a slice or -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)
// -1

HasPrefix

Returns true if the collection has the prefix.

ok := lo.HasPrefix([]int{1, 2, 3, 4}, []int{42})
// false

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

[play]

HasSuffix

Returns true if the collection has the suffix.

ok := lo.HasSuffix([]int{1, 2, 3, 4}, []int{42})
// false

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

[play]

Find

Searches for an element in a slice based on a predicate. 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"
})
// "", false

// Use FindErr when the predicate can return an error
str, err := lo.FindErr([]string{"a", "b", "c", "d"}, func(i string) (bool, error) {
    if i == "c" {
        return false, fmt.Errorf("c is not allowed")
    }
    return i == "b", nil
})
// "b", nil

str, err = lo.FindErr([]string{"a", "b", "c"}, func(i string) (bool, error) {
    if i == "b" {
        return false, fmt.Errorf("b is not allowed")
    }
    return i == "b", nil
})
// "", error("b is not allowed")

[play]

FindIndexOf

FindIndexOf searches for an element in a slice based on a predicate and returns the index and true. 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, false

[play]

FindLastIndexOf

FindLastIndexOf searches for the last element in a slice based on a predicate and returns the index and true. 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, false

[play]

FindOrElse

Searches for an element in a slice based on a predicate. 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"

FindKey

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", true

FindKeyBy

Returns the key of the first element predicate returns true 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
})
// "", false

FindUniques

Returns a slice with all the elements that appear in the collection only once. The order of result values is determined by the order they occur in the slice.

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

FindUniquesBy

Returns a slice with all the elements that appear in the collection only once. The order of result values is determined by the order they occur in the slice. It accepts iteratee which is invoked for each element in the slice 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}

FindDuplicates

Returns a slice with the first occurrence of each duplicated element in the collection. The order of result values is determined by the order they occur in the slice.

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

FindDuplicatesBy

Returns a slice with the first occurrence of each duplicated element in the collection. The order of result values is determined by the order they occur in the slice. It accepts iteratee which is invoked for each element in the slice 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}

With error handling:

duplicatedValues, err := lo.FindDuplicatesByErr([]int{3, 4, 5, 6, 7}, func(i int) (int, error) {
    if i == 5 {
        return 0, fmt.Errorf("number 5 is not allowed")
    }
    return i % 3, nil
})
// []int(nil), error("number 5 is not allowed")

Min

Search the minimum value of a collection.

Returns zero value when the collection is empty.

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

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

min := lo.Min([]time.Duration{time.Second, time.Hour})
// 1s

[play]

MinIndex

Search the minimum value of a collection and the index of the minimum value.

Returns (zero value, -1) when the collection is empty.

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

min, index := lo.MinIndex([]int{})
// 0, -1

min, index := lo.MinIndex([]time.Duration{time.Second, time.Hour})
// 1s, 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.

Returns zero value when the 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)
})
// ""

// Use MinByErr when the comparison function can return an error
min, err := lo.MinByErr([]string{"s1", "string2", "s3"}, func(item string, min string) (bool, error) {
    if item == "string2" {
        return false, fmt.Errorf("string2 is not allowed")
    }
    return len(item) < len(min), nil
})
// "s1", error("string2 is not allowed")

MinIndexBy

Search the minimum value of a collection using the given comparison function and the index of the minimum value.

If several values of the collection are equal to the smallest value, returns the first such value.

Returns (zero value, -1) when the collection is empty.

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

min, index := lo.MinIndexBy([]string{}, func(item string, min string) bool {
    return len(item) < len(min)
})
// "", -1

min, index, err := lo.MinIndexByErr([]string{"s1", "string2", "s3"}, func(item string, min string) (bool, error) {
    if item == "s2" {
        return false, fmt.Errorf("s2 is not allowed")
    }
    return len(item) < len(min), nil
})
// "s1", 0, error("s2 is not allowed")

Earliest

Search the minimum time.Time of a collection.

Returns zero value when the collection is empty.

earliest := lo.Earliest(time.Now(), time.Time{})
// 0001-01-01 00:00:00 +0000 UTC

EarliestBy

Search the minimum time.Time of a collection using the given iteratee function.

Returns zero value when the collection is empty.

type foo struct {
    bar time.Time
}

earliest := lo.EarliestBy([]foo{{time.Now()}, {}}, func(i foo) time.Time {
    return i.bar
})
// {bar:{2023-04-01 01:02:03 +0000 UTC}}

// Use EarliestByErr when the iteratee function can return an error
earliest, err := lo.EarliestByErr([]foo{{time.Now()}, {}}, func(i foo) (time.Time, error) {
    if i.bar.IsZero() {
        return time.Time{}, fmt.Errorf("zero time not allowed")
    }
    return i.bar, nil
})
// {bar:{...}}, error("zero time not allowed")

Max

Search the maximum value of a collection.

Returns zero value when the collection is empty.

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

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

max := lo.Max([]time.Duration{time.Second, time.Hour})
// 1h

MaxIndex

Search the maximum value of a collection and the index of the maximum value.

Returns (zero value, -1) when the collection is empty.

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

max, index := lo.MaxIndex([]int{})
// 0, -1

max, index := lo.MaxIndex([]time.Duration{time.Second, time.Hour})
// 1h, 1

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.

Returns zero value when the 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)
})
// ""

// Use MaxByErr when the comparison function can return an error
max, err := lo.MaxByErr([]string{"string1", "s2", "string3"}, func(item string, max string) (bool, error) {
    if item == "s2" {
        return false, fmt.Errorf("s2 is not allowed")
    }
    return len(item) > len(max), nil
})
// "string1", error("s2 is not allowed")

[play]

MaxIndexBy

Search the maximum value of a collection using the given comparison function and the index of the maximum value.

If several values of the collection are equal to the greatest value, returns the first such value.

Returns (zero value, -1) when the collection is empty.

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

max, index := lo.MaxIndexBy([]string{}, func(item string, max string) bool {
    return len(item) > len(max)
})
// "", -1

// Use MaxIndexByErr when the comparison function can return an error
max, index, err := lo.MaxIndexByErr([]string{"string1", "s2", "string3"}, func(item string, max string) (bool, error) {
    if item == "s2" {
        return false, fmt.Errorf("s2 is not allowed")
    }
    return len(item) > len(max), nil
})
// "string1", 0, error("s2 is not allowed")

[play]

Latest

Search the maximum time.Time of a collection.

Returns zero value when the collection is empty.

latest := lo.Latest(time.Now(), time.Time{})
// 2023-04-01 01:02:03 +0000 UTC

LatestBy

Search the maximum time.Time of a collection using the given iteratee function.

Returns zero value when the collection is empty.

type foo struct {
    bar time.Time
}

latest := lo.LatestBy([]foo{{time.Now()}, {}}, func(i foo) time.Time {
    return i.bar
})
// {bar:{2023-04-01 01:02:03 +0000 UTC}}

// Use LatestByErr when the iteratee function can return an error
result, err := lo.LatestByErr([]foo{{time.Now()}, {}}, func(i foo) (time.Time, error) {
    if i.bar.IsZero() {
        return time.Time{}, fmt.Errorf("zero time not allowed")
    }
    return i.bar, nil
})
// foo{}, error("zero time not allowed")

First

Returns the first element of a collection and check for availability of the first element.

first, ok := lo.First([]int{1, 2, 3})
// 1, true

first, ok := lo.First([]int{})
// 0, false

FirstOrEmpty

Returns the first element of a collection or zero value if empty.

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

first := lo.FirstOrEmpty([]int{})
// 0

FirstOr

Returns the first element of a collection or the fallback value if empty.

first := lo.FirstOr([]int{1, 2, 3}, 245)
// 1

first := lo.FirstOr([]int{}, 31)
// 31

Last

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

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

last, ok := lo.Last([]int{})
// 0
// false

LastOrEmpty

Returns the last element of a collection or zero value if empty.

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

last := lo.LastOrEmpty([]int{})
// 0

LastOr

Returns the last element of a collection or the fallback value if empty.

last := lo.LastOr([]int{1, 2, 3}, 245)
// 3

last := lo.LastOr([]int{}, 31)
// 31

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{0, 1, 2, 3}, 2)
// 2

nth, err := lo.Nth([]int{0, 1, 2, 3}, -2)
// 2

NthOr

Returns the element at index nth of the collection. If nth is negative, it returns the nth element from the end. If nth is out of slice bounds, it returns the provided fallback value

nth := lo.NthOr([]int{10, 20, 30, 40, 50}, 2, -1)
// 30

nth := lo.NthOr([]int{10, 20, 30, 40, 50}, -1, -1)
// 50

nth := lo.NthOr([]int{10, 20, 30, 40, 50}, 5, -1)
// -1 (fallback value)

NthOrEmpty

Returns the element at index nth of the collection. If nth is negative, it returns the nth element from the end. If nth is out of slice bounds, it returns the zero value for the element type (e.g., 0 for integers, "" for strings, etc).

nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, 2)
// 30

nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, -1)
// 50

nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, 5)
// 0 (zero value for int)

nth := lo.NthOrEmpty([]string{"apple", "banana", "cherry"}, 2)
// "cherry"

nth := lo.NthOrEmpty([]string{"apple", "banana", "cherry"}, 5)
// "" (zero value for string)

Sample

Returns a random item from collection.

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

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

[play]

SampleBy

Returns a random item from collection, using a given random integer generator.

import "math/rand"

r := rand.New(rand.NewSource(42))
lo.SampleBy([]string{"a", "b", "c"}, r.Intn)
// a random string from []string{"a", "b", "c"}, using a seeded random generator

lo.SampleBy([]string{}, r.Intn)
// ""

Samples

Returns N random unique items from collection.

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

SamplesBy

Returns N random unique items from collection, using a given random integer generator.

r := rand.New(rand.NewSource(42))
lo.SamplesBy([]string{"a", "b", "c"}, 3, r.Intn)
// []string{"a", "b", "c"} in random order, using a seeded random generator

Ternary

A single line if/else statement.

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

result := lo.Ternary(false, "a", "b")
// "b"

Take care to avoid dereferencing potentially nil pointers in your A/B expressions, because they are both evaluated. See TernaryF to avoid this problem.

[play]

TernaryF

A single 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]

If / ElseIf / Else

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)
// 3

Using callbacks:

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

Mixed:

result := lo.IfF(true, func () int {
        return 1
    }).
    Else(42)
// 1

[play]

Switch / Case / Default

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]

IsNil

Checks if a value is nil or if it's a reference type with a nil underlying value.

var x int
lo.IsNil(x)
// false

var k struct{}
lo.IsNil(k)
// false

var i *int
lo.IsNil(i)
// true

var ifaceWithNilValue any = (*string)(nil)
lo.IsNil(ifaceWithNilValue)
// true
ifaceWithNilValue == nil
// false

IsNotNil

Checks if a value is not nil or if it's not a reference type with a nil underlying value.

var x int
lo.IsNotNil(x)
// true

var k struct{}
lo.IsNotNil(k)
// true

var i *int
lo.IsNotNil(i)
// false

var ifaceWithNilValue any = (*string)(nil)
lo.IsNotNil(ifaceWithNilValue)
// false
ifaceWithNilValue == nil
// true

ToPtr

Returns a pointer copy of the value.

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

[play]

Nil

Returns a nil pointer of type.

ptr := lo.Nil[float64]()
// nil

EmptyableToPtr

Returns a pointer copy of value if it's nonzero. Otherwise, returns nil pointer.

ptr := lo.EmptyableToPtr(nil)
// nil

ptr := lo.EmptyableToPtr("")
// nil

ptr := lo.EmptyableToPtr([]int{})
// *[]int{}

ptr := lo.EmptyableToPtr("hello world")
// *string{"hello world"}

FromPtr

Returns the pointer value or empty.

str := "hello world"
value := lo.FromPtr(&str)
// "hello world"

value := lo.FromPtr(nil)
// ""

FromPtrOr

Returns the pointer value or the fallback value.

str := "hello world"
value := lo.FromPtrOr(&str, "empty")
// "hello world"

value := lo.FromPtrOr(nil, "empty")
// "empty"

ToSlicePtr

Returns a slice of pointers to each value.

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

FromSlicePtr

Returns a slice with the pointer values. Returns a zero value in case of a nil pointer element.

str1 := "hello"
str2 := "world"

ptr := lo.FromSlicePtr[string]([]*string{&str1, &str2, nil})
// []string{"hello", "world", ""}

ptr := lo.Compact(
    lo.FromSlicePtr[string]([]*string{&str1, &str2, nil}),
)
// []string{"hello", "world"}

FromSlicePtrOr

Returns a slice with the pointer values or the fallback value.

str1 := "hello"
str2 := "world"

ptr := lo.FromSlicePtrOr([]*string{&str1, nil, &str2}, "fallback value")
// []string{"hello", "fallback value", "world"}

[play]

ToAnySlice

Returns a slice with all elements mapped to any type.

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

FromAnySlice

Returns a 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"}, true

Empty

Returns the zero value.

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

IsEmpty

Returns 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"})
// false

IsNotEmpty

Returns 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"})
// true

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(nil, nilStr, &str)
// &"foobar" true

CoalesceOrEmpty

Returns the first non-empty arguments. Arguments must be comparable.

result := lo.CoalesceOrEmpty(0, 1, 2, 3)
// 1

result := lo.CoalesceOrEmpty("")
// ""

var nilStr *string
str := "foobar"
result := lo.CoalesceOrEmpty(nil, nilStr, &str)
// &"foobar"

CoalesceSlice

Returns the first non-zero slice.

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

result, ok := lo.CoalesceSlice(nil, []int{})
// []
// true

result, ok := lo.CoalesceSlice([]int(nil))
// []
// false

CoalesceSliceOrEmpty

Returns the first non-zero slice.

result := lo.CoalesceSliceOrEmpty([]int{1, 2, 3}, []int{4, 5, 6})
// [1, 2, 3]

result := lo.CoalesceSliceOrEmpty(nil, []int{})
// []

CoalesceMap

Returns the first non-zero map.

result, ok := lo.CoalesceMap(map[string]int{"1": 1, "2": 2, "3": 3}, map[string]int{"4": 4, "5": 5, "6": 6})
// {"1": 1, "2": 2, "3": 3}
// true

result, ok := lo.CoalesceMap(nil, map[string]int{})
// {}
// true

result, ok := lo.CoalesceMap(map[string]int(nil))
// {}
// false

CoalesceMapOrEmpty

Returns the first non-zero map.

result := lo.CoalesceMapOrEmpty(map[string]int{"1": 1, "2": 2, "3": 3}, map[string]int{"4": 4, "5": 5, "6": 6})
// {"1": 1, "2": 2, "3": 3}

result := lo.CoalesceMapOrEmpty(nil, map[string]int{})
// {}

Partial

Returns 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)
// 47

[play]

Partial2 -> Partial5

Returns 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)
// 80

[play]

Attempt

Invokes a function N times until it returns valid output. Returns either the caught error or nil.

When the 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 errors.New("failed")
})
// 6
// nil

iter, err := lo.Attempt(2, func(i int) error {
    if i == 5 {
        return nil
    }

    return errors.New("failed")
})
// 2
// error "failed"

iter, err := lo.Attempt(0, func(i int) error {
    if i < 42 {
        return errors.New("failed")
    }

    return nil
})
// 43
// nil

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

[play]

AttemptWithDelay

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

When the 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 errors.New("failed")
})
// 3
// ~ 4 seconds
// nil

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

[play]

AttemptWhile

Invokes a function N times until it returns valid output. Returns either the caught error or nil, along with a bool value to determine whether the function should be invoked again. It will terminate the invoke immediately if the second return value is false.

When the 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) { // let's 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 at cenkalti/backoff.

[play]

AttemptWhileWithDelay

Invokes a function N times until it returns valid output, with a pause between each call. Returns either the caught error or nil, along with a bool value to determine whether the function should be invoked again. It will terminate the invoke immediately if the second return value is false.

When the 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) { // let's 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 at cenkalti/backoff.

[play]

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

[play]

DebounceBy

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]

Throttle

Creates a throttled instance that invokes given functions only once in every interval.

This returns 2 functions, First one is throttled function and Second one is a function to reset interval.

f := func() {
	println("Called once in every 100ms")
}

throttle, reset := lo.NewThrottle(100 * time.Millisecond, f)

for j := 0; j < 10; j++ {
	throttle()
	time.Sleep(30 * time.Millisecond)
}

reset()
throttle()

NewThrottleWithCount is NewThrottle with count limit, throttled function will be invoked count times in every interval.

f := func() {
	println("Called three times in every 100ms")
}

throttle, reset := lo.NewThrottleWithCount(100 * time.Millisecond, f)

for j := 0; j < 10; j++ {
	throttle()
	time.Sleep(30 * time.Millisecond)
}

reset()
throttle()

NewThrottleBy and NewThrottleByWithCount are NewThrottle with sharding key, throttled function will be invoked count times in every interval.

f := func(key string) {
	println(key, "Called three times in every 100ms")
}

throttle, reset := lo.NewThrottleByWithCount(100 * time.Millisecond, f)

for j := 0; j < 10; j++ {
	throttle("foo")
	time.Sleep(30 * time.Millisecond)
}

reset()
throttle()

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 functions with multiple return values, the results will be returned as a tuple inside the channel. For functions 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"})

Transaction

Implements a Saga pattern.

transaction := NewTransaction().
    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, errors.New("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 1

WaitFor

Runs periodically until a condition is validated.

alwaysTrue := func(i int) bool { return true }
alwaysFalse := func(i int) bool { return false }
laterTrue := func(i int) bool {
    return i > 5
}

iterations, duration, ok := lo.WaitFor(alwaysTrue, 10*time.Millisecond, 2 * time.Millisecond)
// 1
// 1ms
// true

iterations, duration, ok := lo.WaitFor(alwaysFalse, 10*time.Millisecond, time.Millisecond)
// 10
// 10ms
// false

iterations, duration, ok := lo.WaitFor(laterTrue, 10*time.Millisecond, time.Millisecond)
// 7
// 7ms
// true

iterations, duration, ok := lo.WaitFor(laterTrue, 10*time.Millisecond, 5*time.Millisecond)
// 2
// 10ms
// false

[play]

WaitForWithContext

Runs periodically until a condition is validated or context is invalid.

The condition receives also the context, so it can invalidate the process in the condition checker

ctx := context.Background()

alwaysTrue := func(_ context.Context, i int) bool { return true }
alwaysFalse := func(_ context.Context, i int) bool { return false }
laterTrue := func(_ context.Context, i int) bool {
    return i >= 5
}

iterations, duration, ok := lo.WaitForWithContext(ctx, alwaysTrue, 10*time.Millisecond, 2 * time.Millisecond)
// 1
// 1ms
// true

iterations, duration, ok := lo.WaitForWithContext(ctx, alwaysFalse, 10*time.Millisecond, time.Millisecond)
// 10
// 10ms
// false

iterations, duration, ok := lo.WaitForWithContext(ctx, laterTrue, 10*time.Millisecond, time.Millisecond)
// 5
// 5ms
// true

iterations, duration, ok := lo.WaitForWithContext(ctx, laterTrue, 10*time.Millisecond, 5*time.Millisecond)
// 2
// 10ms
// false

expiringCtx, cancel := context.WithTimeout(ctx, 5*time.Millisecond)
iterations, duration, ok := lo.WaitForWithContext(expiringCtx, alwaysFalse, 100*time.Millisecond, time.Millisecond)
// 5
// 5.1ms
// false

[play]

Validate

Helper 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]

Must

Wraps a function call and 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{0->6}

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(list, item), "'%s' must always contain '%s'", list, item)
...

[play]

Try

Calls the function and returns false in case of error and 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 errors.New("error")
})
// false

[play]

Try{0->6}

The same behavior as Try, but the callback returns 2 variables.

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

[play]

TryOr

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", errors.New("error")
}, "world")
// world
// false

[play]

TryOr{0->6}

The same behavior as TryOr, but the 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]

TryWithErrorValue

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

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

[play]

TryCatch

The same behavior as 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]

TryCatchWithErrorValue

The same behavior as 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]

ErrorsAs

A shortcut for:

err := doSomething()

var rateLimitErr *RateLimitError
if ok := errors.As(err, &rateLimitErr); ok {
    // retry later
}

single line lo helper:

err := doSomething()

if rateLimitErr, ok := lo.ErrorsAs[*RateLimitError](err); ok {
    // retry later
}

[play]

Assert

Does nothing when the condition is true, otherwise it panics with an optional message.

Think twice before using it, given that Go intentionally omits assertions from its standard library.

age := getUserAge()

lo.Assert(age >= 15)

age := getUserAge()

lo.Assert(age >= 15, "user age must be >= 15")

[play]

Assertf

Like Assert, but with fmt.Printf-like formatting.

Think twice before using it, given that Go intentionally omits assertions from its standard library.

age := getUserAge()

lo.Assertf(age >= 15, "user age must be >= 15, got %d", age)

[play]

🛩 Benchmark

We executed a simple benchmark with 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 reflection-based Map implementation.
• lo.Map has the same allocation profile as 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 is useful for long-running callbacks, such as i/o bound processing.
• for beats other implementations for memory and CPU.

🤝 Contributing

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

# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

👤 Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2022 Samuel Berthe.

This project is under MIT license.