Add reverse find functions (#26)

Add new functions related to finding items in arrays in reverse:

- `Array.reverseFind`
- `Array.reverseFindIndex`
- `Array.reverseFindIndexByValue`
- `Array.reverseFindMap`

Author: jeparlefrancais

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- add `Array.reverseFind`, `Array.reverseFindIndex`, `Array.reverseFindIndexByValue`, and `Array.reverseFindMap` ([#26](https://github.com/seaofvoices/luau-disk/pull/26))
 - add `Set.intersect` ([#25](https://github.com/seaofvoices/luau-disk/pull/25))
 - add `Set.toArray` ([#24](https://github.com/seaofvoices/luau-disk/pull/24))
 - add `Set.removeValues` ([#23](https://github.com/seaofvoices/luau-disk/pull/23))

src/array/__tests__/reverseFind.test.lua

@@ -0,0 +1,44 @@
+local jestGlobals = require('@pkg/@jsdotlua/jest-globals')
+
+local reverseFind = require('../reverseFind')
+
+local expect = jestGlobals.expect
+local it = jestGlobals.it
+
+it('finds the last element matching the predicate', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFind(array, function(element)
+        return element % 2 == 0
+    end)
+
+    expect(result).toBe(4)
+end)
+
+it('returns nil when no element matches', function()
+    local array = { 1, 3, 5, 7, 9 }
+    local result = reverseFind(array, function(element)
+        return element % 2 == 0
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+it('starts from the given index', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFind(array, function(element)
+        return element % 2 == 0
+    end, 3)
+
+    expect(result).toBe(2)
+end)
+
+it('handles empty array', function()
+    local array = {}
+    local result = reverseFind(array, function(_element)
+        return true
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+return nil

src/array/__tests__/reverseFindIndex.test.lua

@@ -0,0 +1,44 @@
+local jestGlobals = require('@pkg/@jsdotlua/jest-globals')
+
+local reverseFindIndex = require('../reverseFindIndex')
+
+local expect = jestGlobals.expect
+local it = jestGlobals.it
+
+it('finds the index of the last element matching the predicate', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFindIndex(array, function(element)
+        return element % 2 == 0
+    end)
+
+    expect(result).toBe(4)
+end)
+
+it('returns nil when no element matches', function()
+    local array = { 1, 3, 5, 7, 9 }
+    local result = reverseFindIndex(array, function(element)
+        return element % 2 == 0
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+it('starts from the given index', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFindIndex(array, function(element)
+        return element % 2 == 0
+    end, 3)
+
+    expect(result).toBe(2)
+end)
+
+it('handles empty array', function()
+    local array = {}
+    local result = reverseFindIndex(array, function(_element)
+        return true
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+return nil

src/array/__tests__/reverseFindIndexByValue.test.lua

@@ -0,0 +1,36 @@
+local jestGlobals = require('@pkg/@jsdotlua/jest-globals')
+
+local reverseFindIndexByValue = require('../reverseFindIndexByValue')
+
+local expect = jestGlobals.expect
+local it = jestGlobals.it
+
+it('finds the index of the last matching value', function()
+    local array = { 1, 2, 3, 2, 4 }
+    local result = reverseFindIndexByValue(array, 2)
+
+    expect(result).toBe(4)
+end)
+
+it('returns nil when value is not found', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFindIndexByValue(array, 6)
+
+    expect(result).toBe(nil)
+end)
+
+it('starts from the given index', function()
+    local array = { 1, 2, 3, 2, 4 }
+    local result = reverseFindIndexByValue(array, 2, 3)
+
+    expect(result).toBe(2)
+end)
+
+it('handles empty array', function()
+    local array = {}
+    local result = reverseFindIndexByValue(array, 1)
+
+    expect(result).toBe(nil)
+end)
+
+return nil

src/array/__tests__/reverseFindMap.test.lua

@@ -0,0 +1,53 @@
+local jestGlobals = require('@pkg/@jsdotlua/jest-globals')
+
+local reverseFindMap = require('../reverseFindMap')
+
+local expect = jestGlobals.expect
+local it = jestGlobals.it
+
+it('returns the first non-nil mapped value from the end', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFindMap(array, function(element)
+        if element % 2 == 0 then
+            return element * 2
+        end
+        return nil
+    end)
+
+    expect(result).toBe(8)
+end)
+
+it('returns nil when no mapped value is non-nil', function()
+    local array = { 1, 3, 5, 7, 9 }
+    local result = reverseFindMap(array, function(element)
+        if element % 2 == 0 then
+            return element * 2
+        end
+        return nil
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+it('starts from the given index', function()
+    local array = { 1, 2, 3, 4, 5 }
+    local result = reverseFindMap(array, function(element)
+        if element % 2 == 0 then
+            return element * 2
+        end
+        return nil
+    end, 3)
+
+    expect(result).toBe(4)
+end)
+
+it('handles empty array', function()
+    local array = {}
+    local result = reverseFindMap(array, function(element)
+        return element
+    end)
+
+    expect(result).toBe(nil)
+end)
+
+return nil

src/array/reverseFind.lua

@@ -0,0 +1,18 @@
+local function reverseFind<T>(
+    array: { T },
+    predicate: (element: T, index: number) -> boolean,
+    start: number?
+): T?
+    local length = #array
+
+    for i = start or length, 1, -1 do
+        local element = array[i]
+        if predicate(element, i) then
+            return element
+        end
+    end
+
+    return nil
+end
+
+return reverseFind

src/array/reverseFindIndex.lua

@@ -0,0 +1,18 @@
+local function reverseFindIndex<T>(
+    array: { T },
+    predicate: (element: T, index: number) -> boolean,
+    start: number?
+): number?
+    local length = #array
+
+    for i = start or length, 1, -1 do
+        local element = array[i]
+        if predicate(element, i) then
+            return i
+        end
+    end
+
+    return nil
+end
+
+return reverseFindIndex

src/array/reverseFindIndexByValue.lua

@@ -0,0 +1,13 @@
+local function reverseFindIndexByValue<T>(array: { T }, element: T, start: number?): number?
+    local length = #array
+
+    for i = start or length, 1, -1 do
+        if array[i] == element then
+            return i
+        end
+    end
+
+    return nil
+end
+
+return reverseFindIndexByValue

src/array/reverseFindMap.lua

@@ -0,0 +1,19 @@
+local function reverseFindMap<T, U>(
+    array: { T },
+    mapFn: (element: T, index: number) -> U?,
+    start: number?
+): U?
+    local length = #array
+
+    for i = start or length, 1, -1 do
+        local element = array[i]
+        local result = mapFn(element, i)
+        if result ~= nil then
+            return result
+        end
+    end
+
+    return nil
+end
+
+return reverseFindMap

src/init.lua

@@ -44,6 +44,10 @@ local Disk = {
         removeValues = require('./array/removeValues'),
         reverse = require('./array/reverse'),
         reversed = require('./array/reverse'),
+        reverseFind = require('./array/reverseFind'),
+        reverseFindIndex = require('./array/reverseFindIndex'),
+        reverseFindIndexByValue = require('./array/reverseFindIndexByValue'),
+        reverseFindMap = require('./array/reverseFindMap'),
         sort = require('./array/sort'),
         sortByKey = require('./array/sortByKey'),
         stepBy = require('./array/stepBy'),