From ffebaa48dc9f7fe616a7aea8425de20d35522db1 Mon Sep 17 00:00:00 2001
From: Samuel Berthe <dev@samuel-berthe.fr>
Date: Wed, 24 Sep 2025 23:18:12 +0200
Subject: [PATCH] doc: add examples for find.go

---
 find_example_test.go | 644 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 644 insertions(+)
 create mode 100644 find_example_test.go

diff --git a/find_example_test.go b/find_example_test.go
new file mode 100644
index 0000000..fdf5832
--- /dev/null
+++ b/find_example_test.go
@@ -0,0 +1,644 @@
+package lo
+
+import (
+	"fmt"
+	"time"
+)
+
+func ExampleIndexOf() {
+	list := []string{"foo", "bar", "baz"}
+
+	result := IndexOf(list, "bar")
+
+	fmt.Printf("%d", result)
+	// Output: 1
+}
+
+func ExampleIndexOf_notFound() {
+	list := []string{"foo", "bar", "baz"}
+
+	result := IndexOf(list, "qux")
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleLastIndexOf() {
+	list := []string{"foo", "bar", "baz", "bar"}
+
+	result := LastIndexOf(list, "bar")
+
+	fmt.Printf("%d", result)
+	// Output: 3
+}
+
+func ExampleLastIndexOf_notFound() {
+	list := []string{"foo", "bar", "baz"}
+
+	result := LastIndexOf(list, "qux")
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleFind() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 35},
+	}
+
+	result, found := Find(users, func(user User) bool {
+		return user.Age > 30
+	})
+
+	fmt.Printf("%s %t", result.Name, found)
+	// Output: Charlie true
+}
+
+func ExampleFind_notFound() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, found := Find(list, func(n int) bool {
+		return n > 10
+	})
+
+	fmt.Printf("%d %t", result, found)
+	// Output: 0 false
+}
+
+func ExampleFindIndexOf() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, index, found := FindIndexOf(list, func(n int) bool {
+		return n > 2
+	})
+
+	fmt.Printf("%d %d %t", result, index, found)
+	// Output: 3 2 true
+}
+
+func ExampleFindIndexOf_notFound() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, index, found := FindIndexOf(list, func(n int) bool {
+		return n > 10
+	})
+
+	fmt.Printf("%d %d %t", result, index, found)
+	// Output: 0 -1 false
+}
+
+func ExampleFindLastIndexOf() {
+	list := []int{1, 2, 3, 4, 3, 5}
+
+	result, index, found := FindLastIndexOf(list, func(n int) bool {
+		return n == 3
+	})
+
+	fmt.Printf("%d %d %t", result, index, found)
+	// Output: 3 4 true
+}
+
+func ExampleFindLastIndexOf_notFound() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, index, found := FindLastIndexOf(list, func(n int) bool {
+		return n > 10
+	})
+
+	fmt.Printf("%d %d %t", result, index, found)
+	// Output: 0 -1 false
+}
+
+func ExampleFindOrElse() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := FindOrElse(list, -1, func(n int) bool {
+		return n > 10
+	})
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleFindOrElse_found() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := FindOrElse(list, -1, func(n int) bool {
+		return n > 3
+	})
+
+	fmt.Printf("%d", result)
+	// Output: 4
+}
+
+func ExampleFindKey() {
+	users := map[string]int{
+		"Alice":   25,
+		"Bob":     30,
+		"Charlie": 35,
+	}
+
+	key, found := FindKey(users, 30)
+
+	fmt.Printf("%s %t", key, found)
+	// Output: Bob true
+}
+
+func ExampleFindKey_notFound() {
+	users := map[string]int{
+		"Alice":   25,
+		"Bob":     30,
+		"Charlie": 35,
+	}
+
+	key, found := FindKey(users, 40)
+
+	fmt.Printf("%s %t", key, found)
+	// Output:  false
+}
+
+func ExampleFindKeyBy() {
+	users := map[string]int{
+		"Alice":   25,
+		"Bob":     30,
+		"Charlie": 35,
+	}
+
+	key, found := FindKeyBy(users, func(name string, age int) bool {
+		return age > 30
+	})
+
+	fmt.Printf("%s %t", key, found)
+	// Output: Charlie true
+}
+
+func ExampleFindKeyBy_notFound() {
+	users := map[string]int{
+		"Alice":   25,
+		"Bob":     30,
+		"Charlie": 35,
+	}
+
+	key, found := FindKeyBy(users, func(name string, age int) bool {
+		return age > 40
+	})
+
+	fmt.Printf("%s %t", key, found)
+	// Output:  false
+}
+
+func ExampleFindUniques() {
+	list := []int{1, 2, 2, 3, 3, 3, 4, 5}
+
+	result := FindUniques(list)
+
+	fmt.Printf("%v", result)
+	// Output: [1 4 5]
+}
+
+func ExampleFindUniquesBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 25},
+		{Name: "David", Age: 30},
+		{Name: "Eve", Age: 35},
+	}
+
+	result := FindUniquesBy(users, func(user User) int {
+		return user.Age
+	})
+
+	fmt.Printf("%d", len(result))
+	// Output: 1
+}
+
+func ExampleFindDuplicates() {
+	list := []int{1, 2, 2, 3, 3, 3, 4, 5}
+
+	result := FindDuplicates(list)
+
+	fmt.Printf("%v", result)
+	// Output: [2 3]
+}
+
+func ExampleFindDuplicatesBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 25},
+		{Name: "David", Age: 30},
+		{Name: "Eve", Age: 35},
+	}
+
+	result := FindDuplicatesBy(users, func(user User) int {
+		return user.Age
+	})
+
+	fmt.Printf("%d", len(result))
+	// Output: 2
+}
+
+func ExampleMin() {
+	list := []int{3, 1, 4, 1, 5, 9, 2, 6}
+
+	result := Min(list)
+
+	fmt.Printf("%d", result)
+	// Output: 1
+}
+
+func ExampleMin_empty() {
+	list := []int{}
+
+	result := Min(list)
+
+	fmt.Printf("%d", result)
+	// Output: 0
+}
+
+func ExampleMinIndex() {
+	list := []int{3, 1, 4, 1, 5, 9, 2, 6}
+
+	result, index := MinIndex(list)
+
+	fmt.Printf("%d %d", result, index)
+	// Output: 1 1
+}
+
+func ExampleMinIndex_empty() {
+	list := []int{}
+
+	result, index := MinIndex(list)
+
+	fmt.Printf("%d %d", result, index)
+	// Output: 0 -1
+}
+
+func ExampleMinBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 35},
+	}
+
+	result := MinBy(users, func(a, b User) bool {
+		return a.Age < b.Age
+	})
+
+	fmt.Printf("%s", result.Name)
+	// Output: Alice
+}
+
+func ExampleMinIndexBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 35},
+	}
+
+	result, index := MinIndexBy(users, func(a, b User) bool {
+		return a.Age < b.Age
+	})
+
+	fmt.Printf("%s %d", result.Name, index)
+	// Output: Alice 0
+}
+
+func ExampleEarliest() {
+	now := time.Now()
+	past := now.Add(-time.Hour)
+	future := now.Add(time.Hour)
+
+	result := Earliest(future, now, past)
+
+	fmt.Printf("%t", result.Equal(past))
+	// Output: true
+}
+
+func ExampleEarliestBy() {
+	type Event struct {
+		Name string
+		Time time.Time
+	}
+
+	now := time.Now()
+	events := []Event{
+		{Name: "Event A", Time: now.Add(time.Hour)},
+		{Name: "Event B", Time: now},
+		{Name: "Event C", Time: now.Add(-time.Hour)},
+	}
+
+	result := EarliestBy(events, func(event Event) time.Time {
+		return event.Time
+	})
+
+	fmt.Printf("%s", result.Name)
+	// Output: Event C
+}
+
+func ExampleMax() {
+	list := []int{3, 1, 4, 1, 5, 9, 2, 6}
+
+	result := Max(list)
+
+	fmt.Printf("%d", result)
+	// Output: 9
+}
+
+func ExampleMax_empty() {
+	list := []int{}
+
+	result := Max(list)
+
+	fmt.Printf("%d", result)
+	// Output: 0
+}
+
+func ExampleMaxIndex() {
+	list := []int{3, 1, 4, 1, 5, 9, 2, 6}
+
+	result, index := MaxIndex(list)
+
+	fmt.Printf("%d %d", result, index)
+	// Output: 9 5
+}
+
+func ExampleMaxIndex_empty() {
+	list := []int{}
+
+	result, index := MaxIndex(list)
+
+	fmt.Printf("%d %d", result, index)
+	// Output: 0 -1
+}
+
+func ExampleMaxBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 35},
+	}
+
+	result := MaxBy(users, func(a, b User) bool {
+		return a.Age > b.Age
+	})
+
+	fmt.Printf("%s", result.Name)
+	// Output: Charlie
+}
+
+func ExampleMaxIndexBy() {
+	type User struct {
+		Name string
+		Age  int
+	}
+
+	users := []User{
+		{Name: "Alice", Age: 25},
+		{Name: "Bob", Age: 30},
+		{Name: "Charlie", Age: 35},
+	}
+
+	result, index := MaxIndexBy(users, func(a, b User) bool {
+		return a.Age > b.Age
+	})
+
+	fmt.Printf("%s %d", result.Name, index)
+	// Output: Charlie 2
+}
+
+func ExampleLatest() {
+	now := time.Now()
+	past := now.Add(-time.Hour)
+	future := now.Add(time.Hour)
+
+	result := Latest(future, now, past)
+
+	fmt.Printf("%t", result.Equal(future))
+	// Output: true
+}
+
+func ExampleLatestBy() {
+	type Event struct {
+		Name string
+		Time time.Time
+	}
+
+	now := time.Now()
+	events := []Event{
+		{Name: "Event A", Time: now.Add(time.Hour)},
+		{Name: "Event B", Time: now},
+		{Name: "Event C", Time: now.Add(-time.Hour)},
+	}
+
+	result := LatestBy(events, func(event Event) time.Time {
+		return event.Time
+	})
+
+	fmt.Printf("%s", result.Name)
+	// Output: Event A
+}
+
+func ExampleFirst() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, found := First(list)
+
+	fmt.Printf("%d %t", result, found)
+	// Output: 1 true
+}
+
+func ExampleFirst_empty() {
+	list := []int{}
+
+	result, found := First(list)
+
+	fmt.Printf("%d %t", result, found)
+	// Output: 0 false
+}
+
+func ExampleFirstOrEmpty() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := FirstOrEmpty(list)
+
+	fmt.Printf("%d", result)
+	// Output: 1
+}
+
+func ExampleFirstOrEmpty_empty() {
+	list := []int{}
+
+	result := FirstOrEmpty(list)
+
+	fmt.Printf("%d", result)
+	// Output: 0
+}
+
+func ExampleFirstOr() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := FirstOr(list, -1)
+
+	fmt.Printf("%d", result)
+	// Output: 1
+}
+
+func ExampleFirstOr_empty() {
+	list := []int{}
+
+	result := FirstOr(list, -1)
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleLast() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, found := Last(list)
+
+	fmt.Printf("%d %t", result, found)
+	// Output: 5 true
+}
+
+func ExampleLast_empty() {
+	list := []int{}
+
+	result, found := Last(list)
+
+	fmt.Printf("%d %t", result, found)
+	// Output: 0 false
+}
+
+func ExampleLastOrEmpty() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := LastOrEmpty(list)
+
+	fmt.Printf("%d", result)
+	// Output: 5
+}
+
+func ExampleLastOrEmpty_empty() {
+	list := []int{}
+
+	result := LastOrEmpty(list)
+
+	fmt.Printf("%d", result)
+	// Output: 0
+}
+
+func ExampleLastOr() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := LastOr(list, -1)
+
+	fmt.Printf("%d", result)
+	// Output: 5
+}
+
+func ExampleLastOr_empty() {
+	list := []int{}
+
+	result := LastOr(list, -1)
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleNth() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, err := Nth(list, 2)
+
+	fmt.Printf("%d %v", result, err)
+	// Output: 3 <nil>
+}
+
+func ExampleNth_negative() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, err := Nth(list, -2)
+
+	fmt.Printf("%d %v", result, err)
+	// Output: 4 <nil>
+}
+
+func ExampleNth_outOfBounds() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result, err := Nth(list, 10)
+
+	fmt.Printf("%d %v", result, err)
+	// Output: 0 nth: 10 out of slice bounds
+}
+
+func ExampleNthOr() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := NthOr(list, 2, -1)
+
+	fmt.Printf("%d", result)
+	// Output: 3
+}
+
+func ExampleNthOr_outOfBounds() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := NthOr(list, 10, -1)
+
+	fmt.Printf("%d", result)
+	// Output: -1
+}
+
+func ExampleNthOrEmpty() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := NthOrEmpty(list, 2)
+
+	fmt.Printf("%d", result)
+	// Output: 3
+}
+
+func ExampleNthOrEmpty_outOfBounds() {
+	list := []int{1, 2, 3, 4, 5}
+
+	result := NthOrEmpty(list, 10)
+
+	fmt.Printf("%d", result)
+	// Output: 0
+}