feat: Add NthOr and NthOrEmpty functions (#611)

* feat: Add NthOr and NthOrEmpty functions

This commit introduces two new functions, `NthOr` and `NthOrEmpty`, to the `find` package. These functions provide a safer way to access elements at a specific index in a slice, handling out-of-bounds scenarios gracefully.

- `NthOr`: Returns the element at the specified index or a provided fallback value if the index is out of bounds.
- `NthOrEmpty`: Returns the element at the specified index or the zero value for the slice's element type if the index is out of bounds.

* update readme

Author: edvardsanta

README.md

@@ -253,6 +253,8 @@ Supported search helpers:
 - [LastOrEmpty](#LastOrEmpty)
 - [LastOr](#LastOr)
 - [Nth](#nth)
+- [NthOr](#nthor)
+- [NthOrEmpty](#nthorempty)
 - [Sample](#sample)
 - [SampleBy](#sampleby)
 - [Samples](#samples)
@@ -2803,6 +2805,40 @@ nth, err := lo.Nth([]int{0, 1, 2, 3}, -2)
 // 2
 ```
 
+### NthOr
+
+Returns the element at index `nth` of the collection. If `nth` is negative, it returns the `nth` element from the end. If `nth` is out of slice bounds, it returns the provided fallback value
+```go	
+nth := lo.NthOr([]int{10, 20, 30, 40, 50}, 2, -1)
+// 30
+
+nth := lo.NthOr([]int{10, 20, 30, 40, 50}, -1, -1)
+// 50
+
+nth := lo.NthOr([]int{10, 20, 30, 40, 50}, 5, -1)
+// -1 (fallback value)
+```
+
+### NthOrEmpty
+
+Returns the element at index `nth` of the collection. If `nth` is negative, it returns the `nth` element from the end. If `nth` is out of slice bounds, it returns the zero value for the element type (e.g., 0 for integers, "" for strings, etc).
+``` go
+nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, 2)
+// 30
+
+nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, -1)
+// 50
+
+nth := lo.NthOrEmpty([]int{10, 20, 30, 40, 50}, 5)
+// 0 (zero value for int)
+
+nth := lo.NthOrEmpty([]string{"apple", "banana", "cherry"}, 2)
+// "cherry"
+
+nth := lo.NthOrEmpty([]string{"apple", "banana", "cherry"}, 5)
+// "" (zero value for string)
+```
+
 ### Sample
 
 Returns a random item from collection.
@@ -2815,6 +2851,8 @@ lo.Sample([]string{})
 // ""
 ```
 
+
+
 ### SampleBy
 
 Returns a random item from collection, using a given random integer generator.

find.go

@@ -579,6 +579,29 @@ func Nth[T any, N constraints.Integer](collection []T, nth N) (T, error) {
 	return collection[l+n], nil
 }
 
+// NthOr returns the element at index `nth` of collection.
+// If `nth` is negative, it returns the nth element from the end.
+// If `nth` is out of slice bounds, it returns the fallback value instead of an error.
+func NthOr[T any, N constraints.Integer](collection []T, nth N, fallback T) T {
+	value, err := Nth(collection, nth)
+	if err != nil {
+		return fallback
+	}
+	return value
+}
+
+// NthOrEmpty returns the element at index `nth` of collection.
+// If `nth` is negative, it returns the nth element from the end.
+// If `nth` is out of slice bounds, it returns the zero value (empty value) for that type.
+func NthOrEmpty[T any, N constraints.Integer](collection []T, nth N) T {
+	value, err := Nth(collection, nth)
+	if err != nil {
+		var zeroValue T
+		return zeroValue
+	}
+	return value
+}
+
 // randomIntGenerator is a function that should return a random integer in the range [0, n)
 // where n is the parameter passed to the randomIntGenerator.
 type randomIntGenerator func(n int) int

find_test.go

@@ -630,6 +630,92 @@ func TestNth(t *testing.T) {
 	is.Equal(err6, nil)
 }
 
+func TestNthOr(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+	t.Run("Integers", func(t *testing.T) {
+		const defaultValue = -1
+		intSlice := []int{10, 20, 30, 40, 50}
+
+		is.Equal(30, NthOr(intSlice, 2, defaultValue))
+		is.Equal(50, NthOr(intSlice, -1, defaultValue))
+		is.Equal(defaultValue, NthOr(intSlice, 5, defaultValue))
+	})
+
+	t.Run("Strings", func(t *testing.T) {
+		const defaultValue = "none"
+		strSlice := []string{"apple", "banana", "cherry", "date"}
+
+		is.Equal("banana", NthOr(strSlice, 1, defaultValue))      // Index 1, expected "banana"
+		is.Equal("cherry", NthOr(strSlice, -2, defaultValue))     // Negative index -2, expected "cherry"
+		is.Equal(defaultValue, NthOr(strSlice, 10, defaultValue)) // Out of bounds, fallback "none"
+	})
+
+	t.Run("Structs", func(t *testing.T) {
+		type User struct {
+			ID   int
+			Name string
+		}
+		userSlice := []User{
+			{ID: 1, Name: "Alice"},
+			{ID: 2, Name: "Bob"},
+			{ID: 3, Name: "Charlie"},
+		}
+
+		expectedUser := User{ID: 1, Name: "Alice"}
+		is.Equal(expectedUser, NthOr(userSlice, 0, User{ID: 0, Name: "Unknown"}))
+
+		expectedUser = User{ID: 3, Name: "Charlie"}
+		is.Equal(expectedUser, NthOr(userSlice, -1, User{ID: 0, Name: "Unknown"}))
+
+		expectedUser = User{ID: 0, Name: "Unknown"}
+		is.Equal(expectedUser, NthOr(userSlice, 10, User{ID: 0, Name: "Unknown"}))
+	})
+}
+
+func TestNthOrEmpty(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+	t.Run("Integers", func(t *testing.T) {
+		const defaultValue = 0
+		intSlice := []int{10, 20, 30, 40, 50}
+
+		is.Equal(30, NthOrEmpty(intSlice, 2))
+		is.Equal(50, NthOrEmpty(intSlice, -1))
+		is.Equal(defaultValue, NthOrEmpty(intSlice, 10))
+	})
+
+	t.Run("Strings", func(t *testing.T) {
+		const defaultValue = ""
+		strSlice := []string{"apple", "banana", "cherry", "date"}
+
+		is.Equal("banana", NthOrEmpty(strSlice, 1))
+		is.Equal("cherry", NthOrEmpty(strSlice, -2))
+		is.Equal(defaultValue, NthOrEmpty(strSlice, 10))
+	})
+
+	t.Run("Structs", func(t *testing.T) {
+		type User struct {
+			ID   int
+			Name string
+		}
+		userSlice := []User{
+			{ID: 1, Name: "Alice"},
+			{ID: 2, Name: "Bob"},
+			{ID: 3, Name: "Charlie"},
+		}
+
+		expectedUser := User{ID: 1, Name: "Alice"}
+		is.Equal(expectedUser, NthOrEmpty(userSlice, 0))
+
+		expectedUser = User{ID: 3, Name: "Charlie"}
+		is.Equal(expectedUser, NthOrEmpty(userSlice, -1))
+
+		expectedUser = User{ID: 0, Name: ""}
+		is.Equal(expectedUser, NthOrEmpty(userSlice, 10))
+	})
+}
+
 func TestSample(t *testing.T) {
 	t.Parallel()
 	is := assert.New(t)