doc: adding examples (#230)

README.md

@@ -227,25 +227,29 @@ 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:
 
 ```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.

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 {