lo

lo - Iterate over slices, maps, channels...
lo - 迭代切片、地圖、通道...

✨ samber/lo is a Lodash-style Go library based on Go 1.18+ Generics.
✨ samber/lo是基於 Go 1.18+ 泛型的 Lodash 風格的 Go 函式庫。

This project started as an experiment with the new generics implementation. It may look like Lodash in some aspects. I used to code with the fantastic "go-funk" package, but "go-funk" uses reflection and therefore is not typesafe.
這個計畫最初是作為新泛型實施的實驗而開始的。它在某些方面可能看起來像Lodash 。我曾經使用出色的“go-funk”套件進行編碼，但是“go-funk”使用反射，因此不是類型安全的。

As expected, benchmarks demonstrate that generics are much faster than implementations based on the "reflect" package. Benchmarks also show similar performance gains compared to pure for loops. See below.
如預期的那樣，基準測試表明泛型比基於「reflect」套件的實作快得多。與純for迴圈相比，基準測試也顯示出類似的效能提升。見下文。

In the future, 5 to 10 helpers will overlap with those coming into the Go standard library (under package names slices and maps). I feel this library is legitimate and offers many more valuable abstractions.
將來，5 到 10 個助手將與 Go 標準庫中的助手重疊（在套件名稱slices和maps下）。我覺得這個函式庫是合法的，並且提供了許多更有價值的抽象。

See also:  參見：

• samber/do: A dependency injection toolkit based on Go 1.18+ Generics
  samber/do ：基於 Go 1.18+ Generics 的依賴注入工具包
• samber/mo: Monads based on Go 1.18+ Generics (Option, Result, Either...)
  samber/mo ：基於 Go 1.18+ 泛型的 Monad（Option、Result、Either...）

Why this name?  為什麼叫這個名字？

I wanted a short name, similar to "Lodash" and no Go package currently uses this name.
我想要一個簡短的名稱，類似於“Lodash”，目前沒有 Go 套件使用這個名稱。

🚀 Install  🚀 安裝

go get github.com/samber/lo@v1

This library is v1 and follows SemVer strictly.
該庫是 v1 版並嚴格遵循 SemVer。

No breaking changes will be made to exported APIs before v2.0.0.
v2.0.0 之前匯出的 API 不會發生重大變更。

This library has no dependencies outside the Go standard library.
該庫沒有 Go 標準庫之外的依賴項。

💡 Usage  💡用法

You can import lo using:
您可以使用以下方式匯入lo ：

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

Then use one of the helpers below:
然後使用以下助手之一：

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

Most of the time, the compiler will be able to infer the type so that you can call: lo.Uniq([]string{...}).
大多數時候，編譯器將能夠推斷類型，以便您可以呼叫： lo.Uniq([]string{...}) 。

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.
我不能推薦它，但以防萬一你懶得重複了lo.在任何地方，您都可以將整個庫匯入到命名空間中。

import (
    . "github.com/samber/lo"
)

I take no responsibility on this junk. 😁 💩
我對這些垃圾不負任何責任。 😁💩

🤠 Spec  🤠 規格

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

Supported helpers for slices:
支持的切片助手：

• Filter  篩選
• Map  地圖
• FilterMap  過濾映射
• FlatMap  平面地圖
• Reduce  減少
• ReduceRight  減少右
• ForEach  對於每個
• Times  時代
• Uniq  優尼克
• UniqBy  優衣庫
• GroupBy  分組依據
• Chunk  區塊
• PartitionBy  分區依據
• Flatten  展平
• Interleave  交錯
• Shuffle  隨機播放
• Reverse  反向
• Fill  充滿
• Repeat  重複
• RepeatBy  重複者
• KeyBy  按鍵
• Associate / SliceToMap  關聯/切片到映射
• Drop  降低
• DropRight  右下角
• DropWhile  掉落時
• DropRightWhile  向右下降
• Reject  拒絕
• Count  數數
• CountBy  計數依據
• CountValues  計數值
• CountValuesBy  計數值依據
• Subset  子集
• Slice  片
• Replace  代替
• ReplaceAll  全部替換
• Compact  袖珍的
• IsSorted  已排序
• IsSortedByKey  按鍵排序

Supported helpers for maps:
支援的地圖助理：

• Keys  按鍵
• ValueOr  價值或
• Values  價值觀
• PickBy  提貨人
• PickByKeys  按鍵挑選
• PickByValues  按值挑選
• OmitBy  省略者
• OmitByKeys  按鍵省略
• OmitByValues  按值省略
• Entries / ToPairs  條目/ToPairs
• FromEntries / FromPairs  來自條目/來自對
• Invert  倒置
• Assign (merge of maps)  分配（地圖合併）
• MapKeys  地圖鍵
• MapValues  地圖值
• MapEntries  地圖條目
• MapToSlice  映射到切片

Supported math helpers:  支援的數學助理：

• Range / RangeFrom / RangeWithSteps
  範圍/範圍從/範圍與步驟
• Clamp  夾鉗
• Sum  和
• SumBy  總和

Supported helpers for strings:
支援的字串助手：

• RandomString  隨機字串
• Substring  子字串
• ChunkString  區塊字串
• RuneLength  符文長度

Supported helpers for tuples:
支援的元組助手：

• T2 -> T9
• Unpack2 -> Unpack9  解包2 -> 解包9
• Zip2 -> Zip9
• Unzip2 -> Unzip9  解壓縮2 -> 解壓縮9

Supported helpers for channels:
支援的頻道助手：

• ChannelDispatcher  通道調度器
• SliceToChannel  切片到通道
• Generator  發電機
• Buffer  緩衝
• BufferWithTimeout  超時緩衝區
• FanIn  扇入
• FanOut  扇出

Supported intersection helpers:
支持的交叉路口助手：

• Contains  包含
• ContainsBy  包含者
• Every  每一個
• EveryBy  每個人
• Some  一些
• SomeBy  一些作者
• None  沒有任何
• NoneBy  無作者
• Intersect  相交
• Difference  不同之處
• Union  聯盟
• Without  沒有
• WithoutEmpty  無空

Supported search helpers:
支援的搜尋助手：

• IndexOf  索引
• LastIndexOf  最後索引
• Find  尋找
• FindIndexOf  尋找索引
• FindLastIndexOf  尋找最後一個索引
• FindOrElse  尋找或其他
• FindKey  尋找鑰匙
• FindKeyBy  尋找關鍵字依據
• FindUniques  尋找獨特的
• FindUniquesBy  尋找唯一依據
• FindDuplicates  尋找重複項
• FindDuplicatesBy  尋找重複項
• Min  最小
• MinBy  最小比
• Max  最大限度
• MaxBy  最大比
• Last  最後的
• Nth  第N次
• Sample  樣本
• Samples  樣品

Conditional helpers:  有條件的幫手：

• Ternary  三元
• TernaryF  三元F
• If / ElseIf / Else
  如果/否則如果/否則
• Switch / Case / Default
  開關/案例/預設

Type manipulation helpers:
類型操作助手：

• IsNil  為無
• ToPtr  托普特
• EmptyableToPtr  空指針
• FromPtr  來自指針
• FromPtrOr  來自指針
• ToSlicePtr  切片指針
• ToAnySlice  到任意切片
• FromAnySlice  來自任意切片
• Empty  空的
• IsEmpty  為空
• IsNotEmpty  不為空
• Coalesce  合併

Function helpers:  函數助手：

• Partial  部分的
• Partial2 -> Partial5  部分2 -> 部分5

Concurrency helpers:  並發助手：

• Attempt  試圖
• AttemptWhile  嘗試同時
• AttemptWithDelay  延遲嘗試
• AttemptWhileWithDelay  延遲時嘗試
• Debounce  去抖動
• DebounceBy  反跳通過
• Synchronize  同步
• Async  非同步
• Transaction  交易

Error handling:  錯誤處理：

• Validate  證實
• Must  必須
• Try  嘗試
• Try1 -> Try6  嘗試1 -> 嘗試6
• TryOr  嘗試或
• TryOr1 -> TryOr6
• TryCatch  嘗試捕獲
• TryWithErrorValue  嘗試錯誤值
• TryCatchWithErrorValue  嘗試捕獲錯誤值
• ErrorsAs  錯誤為

Constraints:  限制條件：

• Clonable  可複製

Filter  篩選

Iterates over a collection and returns an array of all the elements the predicate function returns true for.
迭代集合並傳回謂詞函數傳回true的所有元素的陣列。

even := lo.Filter([]int{1, 2, 3, 4}, func(x int, index int) bool {
    return x%2 == 0
})
// []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"

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

[play]  [玩]

Parallel processing: like lo.Map(), but the mapper function is called in a goroutine. Results are returned in the same order.
平行處理：類似於lo.Map() ，但映射器函數是在 goroutine 中呼叫的。結果以相同的順序傳回。

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

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

FilterMap  過濾映射

Returns a slice which obtained after both filtering and mapping using the given callback function.
傳回使用給定回調函數進行過濾和映射後獲得的切片。

The callback function should return two values: the result of the mapping operation and whether the result element should be included or not.
回呼函數應傳回兩個值：映射操作的結果以及是否應包含結果元素。

matching := lo.FilterMap([]string{"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.
操作切片並將其轉換並展平為另一種類型的切片。變換函數可以傳回切片或nil ，並且在nil情況下，不會向最終切片添加任何值。

lo.FlatMap([]int{0, 1, 2}, func(x int, _ int) []string {
  return []string{
    strconv.FormatInt(x, 10),
    strconv.FormatInt(x, 10),
  }
})
// []string{"0", "0", "1", "1", "2", "2"}

[play]  [玩]

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

[play]  [玩]

ReduceRight  減少右

Like lo.Reduce except that it iterates over elements of collection from right to left.
與lo.Reduce類似，只不過它從右到左迭代集合的元素。

result := lo.ReduceRight([][]int{{0, 1}, {2, 3}, {4, 5}}, func(agg []int, item []int, _ int) []int {
    return append(agg, item...)
}, []int{})
// []int{4, 5, 2, 3, 0, 1}

[play]  [玩]

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"

Times

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

import "github.com/samber/lo"

lo.Times(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 an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array.

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

[play]

UniqBy

Returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array. It accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed.

uniqValues := lo.UniqBy([]int{0, 1, 2, 3, 4, 5}, func(i int) int {
    return i%3
})
// []int{0, 1, 2}

[play]

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

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

Chunk

Returns an array of elements split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.

lo.Chunk([]int{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]

PartitionBy

Returns an array of elements split into groups. The order of grouped values is determined by the order they occur in collection. The grouping is generated from the results of running each element of collection through iteratee.

import lo "github.com/samber/lo"

partitions := lo.PartitionBy([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
    if x < 0 {
        return "negative"
    } else if x%2 == 0 {
        return "even"
    }
    return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}

[play]

Parallel processing: like lo.PartitionBy(), but callback is called in goroutine. Results are returned in the same order.

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

partitions := lop.PartitionBy([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func(x int) string {
    if x < 0 {
        return "negative"
    } else if x%2 == 0 {
        return "even"
    }
    return "odd"
})
// [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}}

Flatten

Returns an array a single level deep.

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

[play]

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 an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.

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

[play]

Reverse

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

⚠️ This helper is mutable. This behavior might change in v2.0.0. See #160.

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

[play]

Fill

Fills elements of array with initial value.

type foo struct {
  bar string
}

func (f foo) Clone() foo {
  return foo{f.bar}
}

initializedSlice := lo.Fill([]foo{foo{"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]

KeyBy

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

m := lo.KeyBy([]string{"a", "aa", "aaa"}, func(str string) int {
    return len(str)
})
// map[int]string{1: "a", 2: "aa", 3: "aaa"}

type Character struct {
  dir  string
  code int
}
characters := []Character{
    {dir: "left", code: 97},
    {dir: "right", code: 100},
}
result := lo.KeyBy(characters, func(char Character) string {
    return string(rune(char.code))
})
//map[a:{dir:left code:97} d:{dir:right code:100}]

[play]

Associate (alias: SliceToMap)

Returns a map containing key-value pairs provided by transform function applied to elements of the given slice. If any of two pairs would have the same key the last one gets added to the map.

The order of keys in returned map is not specified and is not guaranteed to be the same from the original array.

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

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

[play]

Drop

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

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

[play]

DropRight

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

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

[play]

DropWhile

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

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

[play]

DropRightWhile

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

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

[play]

Reject

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

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

[play]

Count

Counts the number of elements in the collection that compare equal to 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

[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 ss equivalent to chaining lo.Map and lo.CountValues.

isEven := func(v int) bool {
    return v%2==0
}

lo.CountValuesBy([]int{}, isEven)
// map[bool]int{}

lo.CountValuesBy([]int{1, 2}, isEven)
// map[bool]int{false: 1, true: 1}

lo.CountValuesBy([]int{1, 2, 2}, isEven)
// map[bool]int{false: 1, true: 2}

length := func(v string) int {
    return len(v)
}

lo.CountValuesBy([]string{"foo", "bar", ""}, length)
// map[int]int{0: 1, 3: 2}

lo.CountValuesBy([]string{"foo", "bar", "bar"}, length)
// map[int]int{3: 3}

[play]

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]

Compact

Returns a slice of all non-zero elements.

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

slice := lo.Compact[string](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]

IsSortedByKey

Checks if a slice is sorted by iteratee.

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

[play]

Keys

Creates an array of the map keys.

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

[play]

Values

Creates an array of the map values.

values := lo.Values[string, int](map[string]int{"foo": 1, "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[string, int](map[string]int{"foo": 1, "bar": 2}, "foo", 42)
// 1

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

[play]

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}

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

[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 array of key/value pairs.

entries := lo.Entries(map[string]int{"foo": 1, "bar": 2})
// []lo.Entry[string, int]{
//     {
//         Key: "foo",
//         Value: 1,
//     },
//     {
//         Key: "bar",
//         Value: 2,
//     },
// }

[play]

FromEntries (alias: FromPairs)

Transforms an array of key/value pairs into a map.

m := lo.FromEntries([]lo.Entry[string, int]{
    {
        Key: "foo",
        Value: 1,
    },
    {
        Key: "bar",
        Value: 2,
    },
})
// map[string]int{"foo": 1, "bar": 2}

[play]

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

[play]

MapKeys

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

m2 := lo.MapKeys(map[int]int{1: 1, 2: 2, 3: 3, 4: 4}, func(_ int, v int) string {
    return strconv.FormatInt(int64(v), 10)
})
// map[string]int{"1": 1, "2": 2, "3": 3, "4": 4}

[play]

MapValues

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

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

m2 := lo.MapValues(m1, func(x int64, _ int) string {
    return strconv.FormatInt(x, 10)
})
// map[int]string{1: "1", 2: "2", 3: "3"}

[play]

MapEntries

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

in := map[string]int{"foo": 1, "bar": 2}

out := lo.MapEntries(in, func(k string, v int) (int, string) {
    return v,k
})
// map[int]string{1: "foo", 2: "bar"}

[play]

MapToSlice

Transforms a map into a slice based on specific iteratee.

m := map[int]int64{1: 4, 2: 5, 3: 6}

s := lo.MapToSlice(m, func(k int, v int64) string {
    return fmt.Sprintf("%d_%d", k, v)
})
// []string{"1_4", "2_5", "3_6"}

[play]

Range / RangeFrom / RangeWithSteps

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

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

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

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

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

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

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

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

result := lo.Range(0)
// []

[play]

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]

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 an array of strings split into groups the length of size. If array can't be split evenly, the final chunk will be the remaining elements.

lo.ChunkString("123456", 2)
// []string{"12", "34", "56"}

lo.ChunkString("1234567", 2)
// []string{"12", "34", "56", "7"}

lo.ChunkString("", 2)
// []string{""}

lo.ChunkString("1", 2)
// []string{"1"}

[play]

RuneLength

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

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

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

[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 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 arrays, the second of which contains the second elements of the given arrays, and so on.

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

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

[play]

Unzip2 -> Unzip9

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

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

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

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 channels of collection elements. Channel is closed after last element. Channel capacity can be customized.

list := []int{1, 2, 3, 4, 5}

for v := range lo.SliceToChannel(2, list) {
    println(v)
}
// prints 1, then 2, then 3, then 4, then 5

ChannelToSlice

Returns a slice built from channels items. Blocks until channel closes.

list := []int{1, 2, 3, 4, 5}
ch := lo.SliceToChannel(2, list)

items := ChannelToSlice(ch)
// []int{1, 2, 3, 4, 5}

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

Example: RabbitMQ consumer 👇

ch := readFromQueue()

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

    // do batching stuff

    if !ok {
        break
    }
}

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

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 has no priority. When all upstream channels reach EOF, downstream channel closes.

stream1 := make(chan int, 42)
stream2 := make(chan int, 42)
stream3 := make(chan int, 42)

all := lo.FanIn(100, stream1, stream2, stream3)
// <-chan int

FanOut

Broadcasts all the upstream messages to multiple downstream channels. When upstream channel reach EOF, downstream channels close. If any downstream channels is full, broadcasting is paused.

stream := make(chan int, 42)

all := lo.FanOut(5, 100, stream)
// [5]<-chan int

Contains

Returns true if an element is present in a collection.

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

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

Every

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

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

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

EveryBy

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

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

Some

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

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

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

SomeBy

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

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

None

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

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

NoneBy

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

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

Intersect

Returns the intersection between two collections.

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

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

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

Difference

Returns the difference between two collections.

• The first value is the collection of element absent of list2.
• The second value is the collection of element absent of list1.

left, right := lo.Difference([]int{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{}

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}

Without

Returns slice excluding all given values.

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

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

WithoutEmpty

Returns slice excluding empty values.

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

IndexOf

Returns the index at which the first occurrence of a value is found in an array or return -1 if the value cannot be found.

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

notFound := lo.IndexOf([]int{0, 1, 2, 1, 2, 3}, 6)
// -1

LastIndexOf

Returns the index at which the last occurrence of a value is found in an array or return -1 if the value cannot be found.

found := lo.LastIndexOf([]int{0, 1, 2, 1, 2, 3}, 2)
// 4

notFound := lo.LastIndexOf([]int{0, 1, 2, 1, 2, 3}, 6)
// -1

Find

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

str, ok := lo.Find([]string{"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

FindIndexOf

FindIndexOf searches an element in a slice based on a predicate and returns the index and true. It returns -1 and false if the element is not found.

str, index, ok := lo.FindIndexOf([]string{"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

FindLastIndexOf

FindLastIndexOf searches an element in a slice based on a predicate and returns the index and true. It returns -1 and false if the element is not found.

str, index, ok := lo.FindLastIndexOf([]string{"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

FindOrElse

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

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 truthy for.

result1, ok1 := lo.FindKeyBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(k string, v int) bool {
    return k == "foo"
})
// "foo", true

result2, ok2 := lo.FindKeyBy(map[string]int{"foo": 1, "bar": 2, "baz": 3}, func(k string, v int) bool {
    return false
})
// "", false

FindUniques

Returns a slice with all the unique elements of the collection. The order of result values is determined by the order they occur in the array.

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

FindUniquesBy

Returns a slice with all the unique elements of the collection. The order of result values is determined by the order they occur in the array. It accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed.

uniqueValues := lo.FindUniquesBy([]int{3, 4, 5, 6, 7}, func(i int) int {
    return i%3
})
// []int{5}

FindDuplicates

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

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

FindDuplicatesBy

Returns a slice with the first occurrence of each duplicated elements of the collection. The order of result values is determined by the order they occur in the array. It accepts iteratee which is invoked for each element in array to generate the criterion by which uniqueness is computed.

duplicatedValues := lo.FindDuplicatesBy([]int{3, 4, 5, 6, 7}, func(i int) int {
    return i%3
})
// []int{3, 4}

Min

Search the minimum value of a collection.

Returns zero value when collection is empty.

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

min := lo.Min([]int{})
// 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 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)
})
// ""

Max

Search the maximum value of a collection.

Returns zero value when collection is empty.

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

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

MaxBy

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

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

Returns zero value when collection is empty.

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

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

Last

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

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

Nth

Returns the element at index nth of collection. If nth is negative, the nth element from the end is returned. An error is returned when nth is out of slice bounds.

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

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

Sample

Returns a random item from collection.

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

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

Samples

Returns N random unique items from collection.

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

Ternary

A 1 line if/else statement.

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

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

[play]

TernaryF

A 1 line if/else statement whose options are functions.

result := lo.TernaryF(true, func() string { return "a" }, func() string { return "b" })
// "a"

result := lo.TernaryF(false, func() string { return "a" }, func() string { return "b" })
// "b"

Useful to avoid nil-pointer dereferencing in intializations, 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
IsNil(x))
// false

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

var i *int
IsNil(i)
// true

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

ToPtr

Returns a pointer copy of the value.

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

EmptyableToPtr

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

ptr := lo.EmptyableToPtr[[]int](nil)
// nil

ptr := lo.EmptyableToPtr[string]("")
// nil

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

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

FromPtr

Returns the pointer value or empty.

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

value := lo.FromPtr[string](nil)
// ""

FromPtrOr

Returns the pointer value or the fallback value.

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

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

ToSlicePtr

Returns a slice of pointer copy of value.

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

ToAnySlice

Returns a slice with all elements mapped to any type.

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

FromAnySlice

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

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

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

Empty

Returns an empty 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[*string](nil, nilStr, &str)
// &"foobar" true

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

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

Attempt

Invokes a function N times until it returns valid output. Returning either the caught error or nil. When first argument is less than 1, the function runs until a successful response is returned.

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

    return fmt.Errorf("failed")
})
// 6
// nil

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

    return fmt.Errorf("failed")
})
// 2
// error "failed"

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

    return nil
})
// 43
// nil

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

[play]

AttemptWithDelay

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

When first argument is less than 1, the function runs until a successful response is returned.

iter, duration, err := lo.AttemptWithDelay(5, 2*time.Second, func(i int, duration time.Duration) error {
    if i == 2 {
        return nil
    }

    return fmt.Errorf("failed")
})
// 3
// ~ 4 seconds
// nil

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

[play]

AttemptWhile

Invokes a function N times until it returns valid output. Returning either the caught error or nil, and along with a bool value to identifying whether it needs invoke function continuously. It will terminate the invoke immediately if second bool value is returned with falsy value.

When first argument is less than 1, the function runs until a successful response is returned.

count1, err1 := lo.AttemptWhile(5, func(i int) (error, bool) {
    err := doMockedHTTPRequest(i)
    if err != nil {
        if errors.Is(err, ErrBadRequest) { // lets assume ErrBadRequest is a critical error that needs to terminate the invoke
            return err, false // flag the second return value as false to terminate the invoke
        }

        return err, true
    }

    return nil, false
})

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

[play]

AttemptWhileWithDelay

Invokes a function N times until it returns valid output, with a pause between each call. Returning either the caught error or nil, and along with a bool value to identifying whether it needs to invoke function continuously. It will terminate the invoke immediately if second bool value is returned with falsy value.

When first argument is less than 1, the function runs until a successful response is returned.

count1, time1, err1 := lo.AttemptWhileWithDelay(5, time.Millisecond, func(i int, d time.Duration) (error, bool) {
    err := doMockedHTTPRequest(i)
    if err != nil {
        if errors.Is(err, ErrBadRequest) { // lets assume ErrBadRequest is a critical error that needs to terminate the invoke
            return err, false // flag the second return value as false to terminate the invoke
        }

        return err, true
    }

    return nil, false
})

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

[play]

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]

Synchronize

Wraps the underlying callback in a mutex. It receives an optional mutex.

s := lo.Synchronize()

for i := 0; i < 10; i++ {
    go s.Do(func () {
        println("will be called sequentially")
    })
}

It is equivalent to:

mu := sync.Mutex{}

func foobar() {
    mu.Lock()
    defer mu.Unlock()

    // ...
}

Async

Executes a function in a goroutine and returns the result in a channel.

ch := lo.Async(func() error { time.Sleep(10 * time.Second); return nil })
// chan error (nil)

Async{0->6}

Executes a function in a goroutine and returns the result in a channel. For function with multiple return values, the results will be returned as a tuple inside the channel. For function without return, struct{} will be returned in the channel.

ch := lo.Async0(func() { time.Sleep(10 * time.Second) })
// chan struct{}

ch := lo.Async1(func() int {
  time.Sleep(10 * time.Second);
  return 42
})
// chan int (42)

ch := lo.Async2(func() (int, string) {
  time.Sleep(10 * time.Second);
  return 42, "Hello"
})
// chan lo.Tuple2[int, string] ({42, "Hello"})

Transaction

Implements a Saga pattern.

transaction := NewTransaction[int]().
    Then(
        func(state int) (int, error) {
            fmt.Println("step 1")
            return state + 10, nil
        },
        func(state int) int {
            fmt.Println("rollback 1")
            return state - 10
        },
    ).
    Then(
        func(state int) (int, error) {
            fmt.Println("step 2")
            return state + 15, nil
        },
        func(state int) int {
            fmt.Println("rollback 2")
            return state - 15
        },
    ).
    Then(
        func(state int) (int, error) {
            fmt.Println("step 3")

            if true {
                return state, fmt.Errorf("error")
            }

            return state + 42, nil
        },
        func(state int) int {
            fmt.Println("rollback 3")
            return state - 42
        },
    )

_, _ = transaction.Process(-5)

// Output:
// step 1
// step 2
// step 3
// rollback 2
// rollback 1

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 to panics if second argument is error or false, returns the value otherwise.

val := lo.Must(time.Parse("2006-01-02", "2022-01-15"))
// 2022-01-15

val := lo.Must(time.Parse("2006-01-02", "bad-value"))
// panics

[play]

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

[play]

Try

Calls the function and return false in case of error and on panic.

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

ok := lo.Try(func() error {
    return nil
})
// true

ok := lo.Try(func() error {
    return fmt.Errorf("error")
})
// false

[play]

Try{0->6}

The same behavior than Try, but 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", fmt.Errorf("error")
}, "world")
// world
// false

[play]

TryOr{0->6}

The same behavior than TryOr, but callback returns X variables.

str, nbr, ok := lo.TryOr2(func() (string, int, error) {
    panic("error")
    return "hello", 42, nil
}, "world", 21)
// world
// 21
// false

[play]

TryWithErrorValue

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

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

[play]

TryCatch

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

caught := false

ok := lo.TryCatch(func() error {
    panic("error")
    return nil
}, func() {
    caught = true
})
// false
// caught == true

[play]

TryCatchWithErrorValue

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

caught := false

ok := lo.TryCatchWithErrorValue(func() error {
    panic("error")
    return nil
}, func(val any) {
    caught = val == "error"
})
// false
// caught == true

[play]

ErrorsAs

A shortcut for:

err := doSomething()

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

1 line lo helper:

err := doSomething()

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

[play]

🛩 Benchmark

We executed a simple benchmark with the a dead-simple lo.Map loop:

See the full implementation here.

_ = lo.Map[int64](arr, func(x int64, i int) string {
    return strconv.FormatInt(x, 10)
})

Result:

Here is a comparison between lo.Map, lop.Map, go-funk library and a simple Go for loop.

$ go test -benchmem -bench ./...
goos: linux
goarch: amd64
pkg: github.com/samber/lo
cpu: Intel(R) Core(TM) i5-7267U CPU @ 3.10GHz
cpu: Intel(R) Core(TM) i7 CPU         920  @ 2.67GHz
BenchmarkMap/lo.Map-8         	       8	 132728237 ns/op	39998945 B/op	 1000002 allocs/op
BenchmarkMap/lop.Map-8        	       2	 503947830 ns/op	119999956 B/op	 3000007 allocs/op
BenchmarkMap/reflect-8        	       2	 826400560 ns/op	170326512 B/op	 4000042 allocs/op
BenchmarkMap/for-8            	       9	 126252954 ns/op	39998674 B/op	 1000001 allocs/op
PASS
ok  	github.com/samber/lo	6.657s

• lo.Map is way faster (x7) than go-funk, a reflection-based Map implementation.
• lo.Map have the same allocation profile than for.
• lo.Map is 4% slower than for.
• lop.Map is slower than lo.Map because it implies more memory allocation and locks. lop.Map will be 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.

With Docker

docker-compose run --rm dev

Without Docker

# 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 MIT licensed.