From 4fecc9049cabc32ab09bae41eb1dc6bb4ee5dfa5 Mon Sep 17 00:00:00 2001 From: Samuel Berthe Date: Mon, 3 Oct 2022 19:19:15 +0200 Subject: [PATCH] doc: adding examples (#230) --- README.md | 32 +++++++- slice.go | 15 ++++ slice_example_test.go | 178 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 223 insertions(+), 2 deletions(-) create mode 100644 slice_example_test.go diff --git a/README.md b/README.md index 0bb8b794..4963d2b8 100644 --- a/README.md +++ b/README.md @@ -227,12 +227,14 @@ Constraints: Iterates over a collection and returns an array of all the elements the predicate function returns `true` for. ```go -even := lo.Filter[int]([]int{1, 2, 3, 4}, func(x int, _ int) bool { +even := lo.Filter[int]([]int{1, 2, 3, 4}, func(x int, index int) bool { return x%2 == 0 }) // []int{2, 4} ``` +[[play](https://go.dev/play/p/Apjg3WeSi7K)] + ### Map Manipulates a slice of one type and transforms it into a slice of another type: @@ -240,12 +242,14 @@ Manipulates a slice of one type and transforms it into a slice of another type: ```go import "github.com/samber/lo" -lo.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, _ int) string { +lo.Map[int64, string]([]int64{1, 2, 3, 4}, func(x int64, index int) string { return strconv.FormatInt(x, 10) }) // []string{"1", "2", "3", "4"} ``` +[[play](https://go.dev/play/p/OkPcYAhBo0D)] + Parallel processing: like `lo.Map()`, but the mapper function is called in a goroutine. Results are returned in the same order. ```go @@ -273,6 +277,8 @@ matching := lo.FilterMap[string, string]([]string{"cpu", "gpu", "mouse", "keyboa // []string{"xpu", "xpu"} ``` +[[play](https://go.dev/play/p/-AuYXfy7opz)] + ### FlatMap Manipulates a slice and transforms and flattens it to a slice of another type. @@ -287,6 +293,8 @@ lo.FlatMap[int, string]([]int{0, 1, 2}, func(x int, _ int) []string { // []string{"0", "0", "1", "1", "2", "2"} ``` +[[play](https://go.dev/play/p/YSoYmQTA8-U)] + ### 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. @@ -298,6 +306,8 @@ sum := lo.Reduce[int, int]([]int{1, 2, 3, 4}, func(agg int, item int, _ int) int // 10 ``` +[[play](https://go.dev/play/p/R4UHXZNaaUG)] + ### ReduceRight Like `lo.Reduce` except that it iterates over elements of collection from right to left. @@ -309,6 +319,8 @@ result := lo.ReduceRight[[]int, []int]([][]int{{0, 1}, {2, 3}, {4, 5}}, func(agg // []int{4, 5, 2, 3, 0, 1} ``` +[[play](https://go.dev/play/p/Fq3W70l7wXF)] + ### ForEach Iterates over elements of a collection and invokes the function over each element. @@ -322,6 +334,8 @@ lo.ForEach[string]([]string{"hello", "world"}, func(x string, _ int) { // prints "hello\nworld\n" ``` +[[play](https://go.dev/play/p/oofyiUPRf8t)] + Parallel processing: like `lo.ForEach()`, but the callback is called as a goroutine. ```go @@ -346,6 +360,8 @@ lo.Times[string](3, func(i int) string { // []string{"0", "1", "2"} ``` +[[play](https://go.dev/play/p/vgQj3Glr6lT)] + Parallel processing: like `lo.Times()`, but callback is called in goroutine. ```go @@ -366,6 +382,8 @@ uniqValues := lo.Uniq[int]([]int{1, 2, 2, 1}) // []int{1, 2} ``` +[[play](https://go.dev/play/p/DTzbeXZ6iEN)] + ### 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. @@ -377,6 +395,8 @@ uniqValues := lo.UniqBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func(i int) int { // []int{0, 1, 2} ``` +[[play](https://go.dev/play/p/g42Z3QSb53u)] + ### GroupBy Returns an object composed of keys generated from the results of running each element of collection through iteratee. @@ -390,6 +410,8 @@ groups := lo.GroupBy[int, int]([]int{0, 1, 2, 3, 4, 5}, func(i int) int { // map[int][]int{0: []int{0, 3}, 1: []int{1, 4}, 2: []int{2, 5}} ``` +[[play](https://go.dev/play/p/XnQBd_v6brd)] + Parallel processing: like `lo.GroupBy()`, but callback is called in goroutine. ```go @@ -419,6 +441,8 @@ lo.Chunk[int]([]int{0}, 2) // [][]int{{0}} ``` +[[play](https://go.dev/play/p/EeKl0AuTehH)] + ### 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. @@ -437,6 +461,8 @@ partitions := lo.PartitionBy[int, string]([]int{-2, -1, 0, 1, 2, 3, 4, 5}, func( // [][]int{{-2, -1}, {0, 2, 4}, {1, 3, 5}} ``` +[[play](https://go.dev/play/p/NfQ_nGjkgXW)] + Parallel processing: like `lo.PartitionBy()`, but callback is called in goroutine. Results are returned in the same order. ```go @@ -462,6 +488,8 @@ flat := lo.Flatten[int]([][]int{{0, 1}, {2, 3, 4, 5}}) // []int{0, 1, 2, 3, 4, 5} ``` +[[play](https://go.dev/play/p/rbp9ORaMpjw)] + ### Shuffle Returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm. diff --git a/slice.go b/slice.go index 4d1e9bf3..eb83ec9d 100644 --- a/slice.go +++ b/slice.go @@ -7,6 +7,7 @@ import ( ) // Filter iterates over elements of collection, returning an array of all elements predicate returns truthy for. +// Play: https://go.dev/play/p/Apjg3WeSi7K func Filter[V any](collection []V, predicate func(V, int) bool) []V { result := []V{} @@ -20,6 +21,7 @@ func Filter[V any](collection []V, predicate func(V, int) bool) []V { } // Map manipulates a slice and transforms it to a slice of another type. +// Play: https://go.dev/play/p/OkPcYAhBo0D func Map[T any, R any](collection []T, iteratee func(T, int) R) []R { result := make([]R, len(collection)) @@ -34,6 +36,8 @@ func Map[T any, R any](collection []T, iteratee func(T, int) R) []R { // The callback function should return two values: // - the result of the mapping operation and // - whether the result element should be included or not. +// +// Play: https://go.dev/play/p/-AuYXfy7opz func FilterMap[T any, R any](collection []T, callback func(T, int) (R, bool)) []R { result := []R{} @@ -47,6 +51,7 @@ func FilterMap[T any, R any](collection []T, callback func(T, int) (R, bool)) [] } // FlatMap manipulates a slice and transforms and flattens it to a slice of another type. +// Play: https://go.dev/play/p/YSoYmQTA8-U func FlatMap[T any, R any](collection []T, iteratee func(T, int) []R) []R { result := []R{} @@ -59,6 +64,7 @@ func FlatMap[T any, R any](collection []T, iteratee func(T, int) []R) []R { // Reduce reduces collection to a value which is the accumulated result of running each element in collection // through accumulator, where each successive invocation is supplied the return value of the previous. +// Play: https://go.dev/play/p/R4UHXZNaaUG func Reduce[T any, R any](collection []T, accumulator func(R, T, int) R, initial R) R { for i, item := range collection { initial = accumulator(initial, item, i) @@ -68,6 +74,7 @@ func Reduce[T any, R any](collection []T, accumulator func(R, T, int) R, initial } // ReduceRight helper is like Reduce except that it iterates over elements of collection from right to left. +// Play: https://go.dev/play/p/Fq3W70l7wXF func ReduceRight[T any, R any](collection []T, accumulator func(R, T, int) R, initial R) R { for i := len(collection) - 1; i >= 0; i-- { initial = accumulator(initial, collection[i], i) @@ -77,6 +84,7 @@ func ReduceRight[T any, R any](collection []T, accumulator func(R, T, int) R, in } // ForEach iterates over elements of collection and invokes iteratee for each element. +// Play: https://go.dev/play/p/oofyiUPRf8t func ForEach[T any](collection []T, iteratee func(T, int)) { for i, item := range collection { iteratee(item, i) @@ -85,6 +93,7 @@ func ForEach[T any](collection []T, iteratee func(T, int)) { // Times invokes the iteratee n times, returning an array of the results of each invocation. // The iteratee is invoked with index as argument. +// Play: https://go.dev/play/p/vgQj3Glr6lT func Times[T any](count int, iteratee func(int) T) []T { result := make([]T, count) @@ -97,6 +106,7 @@ func Times[T any](count int, iteratee func(int) T) []T { // Uniq returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. // The order of result values is determined by the order they occur in the array. +// Play: https://go.dev/play/p/DTzbeXZ6iEN func Uniq[T comparable](collection []T) []T { result := make([]T, 0, len(collection)) seen := make(map[T]struct{}, len(collection)) @@ -116,6 +126,7 @@ func Uniq[T comparable](collection []T) []T { // UniqBy returns a duplicate-free version of an array, in which only the first occurrence of each element is kept. // The order of result values is determined by the order they occur in the array. It accepts `iteratee` which is // invoked for each element in array to generate the criterion by which uniqueness is computed. +// Play: https://go.dev/play/p/g42Z3QSb53u func UniqBy[T any, U comparable](collection []T, iteratee func(T) U) []T { result := make([]T, 0, len(collection)) seen := make(map[U]struct{}, len(collection)) @@ -135,6 +146,7 @@ func UniqBy[T any, U comparable](collection []T, iteratee func(T) U) []T { } // GroupBy returns an object composed of keys generated from the results of running each element of collection through iteratee. +// Play: https://go.dev/play/p/XnQBd_v6brd func GroupBy[T any, U comparable](collection []T, iteratee func(T) U) map[U][]T { result := map[U][]T{} @@ -149,6 +161,7 @@ func GroupBy[T any, U comparable](collection []T, iteratee func(T) U) map[U][]T // Chunk returns an array of elements split into groups the length of size. If array can't be split evenly, // the final chunk will be the remaining elements. +// Play: https://go.dev/play/p/EeKl0AuTehH func Chunk[T any](collection []T, size int) [][]T { if size <= 0 { panic("Second parameter must be greater than 0") @@ -175,6 +188,7 @@ func Chunk[T any](collection []T, size int) [][]T { // PartitionBy returns an array of elements split into groups. The order of grouped values is // determined by the order they occur in collection. The grouping is generated from the results // of running each element of collection through iteratee. +// Play: https://go.dev/play/p/NfQ_nGjkgXW func PartitionBy[T any, K comparable](collection []T, iteratee func(x T) K) [][]T { result := [][]T{} seen := map[K]int{} @@ -200,6 +214,7 @@ func PartitionBy[T any, K comparable](collection []T, iteratee func(x T) K) [][] } // Flatten returns an array a single level deep. +// Play: https://go.dev/play/p/rbp9ORaMpjw func Flatten[T any](collection [][]T) []T { totalLen := 0 for i := range collection { diff --git a/slice_example_test.go b/slice_example_test.go new file mode 100644 index 00000000..9214da3f --- /dev/null +++ b/slice_example_test.go @@ -0,0 +1,178 @@ +package lo + +import ( + "fmt" + "strconv" +) + +func ExampleFilter() { + list := []int64{1, 2, 3, 4} + + result := Filter(list, func(nbr int64, index int) bool { + return nbr%2 == 0 + }) + + fmt.Printf("%v", result) + // Output: [2 4] +} + +func ExampleMap() { + list := []int64{1, 2, 3, 4} + + result := Map(list, func(nbr int64, index int) string { + return strconv.FormatInt(nbr*2, 10) + }) + + fmt.Printf("%v", result) + // Output: [2 4 6 8] +} + +func ExampleFilterMap() { + list := []int64{1, 2, 3, 4} + + result := FilterMap(list, func(nbr int64, index int) (string, bool) { + return strconv.FormatInt(nbr*2, 10), nbr%2 == 0 + }) + + fmt.Printf("%v", result) + // Output: [4 8] +} + +func ExampleFlatMap() { + list := []int64{1, 2, 3, 4} + + result := FlatMap(list, func(nbr int64, index int) []string { + return []string{ + strconv.FormatInt(nbr, 10), // base 10 + strconv.FormatInt(nbr, 2), // base 2 + } + }) + + fmt.Printf("%v", result) + // Output: [1 1 2 10 3 11 4 100] +} + +func ExampleReduce() { + list := []int64{1, 2, 3, 4} + + result := Reduce(list, func(agg int64, item int64, index int) int64 { + return agg + item + }, 0) + + fmt.Printf("%v", result) + // Output: 10 +} + +func ExampleReduceRight() { + list := [][]int{{0, 1}, {2, 3}, {4, 5}} + + result := ReduceRight(list, func(agg []int, item []int, index int) []int { + return append(agg, item...) + }, []int{}) + + fmt.Printf("%v", result) + // Output: [4 5 2 3 0 1] +} + +func ExampleForEach() { + list := []int64{1, 2, 3, 4} + + ForEach(list, func(x int64, _ int) { + fmt.Println(x) + }) + + // Output: + // 1 + // 2 + // 3 + // 4 +} + +func ExampleTimes() { + result := Times(3, func(i int) string { + return strconv.FormatInt(int64(i), 10) + }) + + fmt.Printf("%v", result) + // Output: [0 1 2] +} + +func ExampleUniq() { + list := []int{1, 2, 2, 1} + + result := Uniq(list) + + fmt.Printf("%v", result) + // Output: [1 2] +} + +func ExampleUniqBy() { + list := []int{0, 1, 2, 3, 4, 5} + + result := UniqBy(list, func(i int) int { + return i % 3 + }) + + fmt.Printf("%v", result) + // Output: [0 1 2] +} + +func ExampleGroupBy() { + list := []int{0, 1, 2, 3, 4, 5} + + result := GroupBy(list, func(i int) int { + return i % 3 + }) + + for _, item := range result { + fmt.Printf("%v\n", item) + } + // Output: + // [0 3] + // [1 4] + // [2 5] +} + +func ExampleChunk() { + list := []int{0, 1, 2, 3, 4} + + result := Chunk(list, 2) + + for _, item := range result { + fmt.Printf("%v\n", item) + } + // Output: + // [0 1] + // [2 3] + // [4] +} + +func ExamplePartitionBy() { + list := []int{-2, -1, 0, 1, 2, 3, 4} + + result := PartitionBy(list, func(x int) string { + if x < 0 { + return "negative" + } else if x%2 == 0 { + return "even" + } + return "odd" + }) + + for _, item := range result { + fmt.Printf("%v\n", item) + } + // Output: + // [-2 -1] + // [0 2 4] + // [1 3] +} + +func ExampleFlatten() { + list := [][]int{{0, 1, 2}, {3, 4, 5}} + + result := Flatten(list) + + fmt.Printf("%v", result) + // Output: [0 1 2 3 4 5] +}