Merge branch 'openmw_aux' into 'master'

[Lua] Update openmw_aux.util

See merge request OpenMW/openmw!1797

files/builtin_scripts/openmw_aux/util.lua

@@ -6,52 +6,107 @@
 
 local aux_util = {}
 
----
+local function deepToString(val, level, prefix)
--- Works like `tostring` but shows also content of tables.
+    local level = (level or 1) - 1
--- @function [parent=#util] deepToString
--- @param #any value The value to conver to string
--- @param #number maxDepth Max depth of tables unpacking (optional, 2 by default)
-function aux_util.deepToString(val, level, prefix)
-    level = (level or 1) - 1
     local ok, iter, t = pcall(function() return pairs(val) end)
     if level < 0 or not ok then
         return tostring(val)
     end
-    local prefix = prefix or ''
     local newPrefix = prefix .. '  '
     local strs = {tostring(val) .. ' {\n'}
     for k, v in iter, t do
-        strs[#strs + 1] = newPrefix .. tostring(k) .. ' = ' .. aux_util.deepToString(v, level, newPrefix) .. ',\n'
+        strs[#strs + 1] = newPrefix .. tostring(k) .. ' = ' .. deepToString(v, level, newPrefix) .. ',\n'
     end
     strs[#strs + 1] = prefix .. '}'
     return table.concat(strs)
 end
 
--------------------------------------------------------------------------------
+---
--- Finds the nearest object to the given point in the given list.
+-- Works like `tostring` but shows also content of tables.
--- Ignores cells, uses only coordinates. Returns the nearest object,
+-- @function [parent=#util] deepToString
--- and the distance to it. If objectList is empty, returns nil.
+-- @param #any value The value to convert to string
--- @function [parent=#util] findNearestTo
+-- @param #number maxDepth Max depth of tables unpacking (optional, 1 by default)
--- @param openmw.util#Vector3 point
+function aux_util.deepToString(value, maxDepth)
--- @param openmw.core#ObjectList objectList
+    return deepToString(value, maxDepth, '')
--- @param #number minDist (optional) ignore objects that are closer than minDist
+end
--- @param #number maxDist (optional) ignore objects that are farther than maxDist
+
--- @return openmw.core#GameObject, #number the nearest object and the distance
+---
-function aux_util.findNearestTo(point, objectList, minDist, maxDist)
+-- Finds the element the minimizes `scoreFn`.
-    local res = nil
+-- @function [parent=#util] findMinScore
-    local resDist = nil
+-- @param #table array Any array
-    local minDist = minDist or 0
+-- @param #function scoreFn Function that returns either nil/false or a number for each element of the array
-    for i = 1, #objectList do
+-- @return element The element the minimizes `scoreFn`
-        local obj = objectList[i]
+-- @return #number score The output of `scoreFn(element)`
-        local dist = (obj.position - point):length()
+-- @return #number index The index of the chosen element in the array
-        if dist >= minDist and (not res or dist < resDist) then
+-- @usage -- Find the nearest NPC
-            res = obj
+-- local nearestNPC, distToNPC = aux_util.findMinScore(
-            resDist = dist
+--     nearby.actors,
+--     function(actor)
+--         return actor.type == types.NPC and (self.position - actor.position):length()
+--     end)
+function aux_util.findMinScore(array, scoreFn)
+    local bestValue, bestScore, bestIndex
+    for i = 1, #array do
+        local v = array[i]
+        local score = scoreFn(v)
+        if score and (not bestScore or bestScore > score) then
+            bestValue, bestScore, bestIndex = v, score, i
         end
     end
-    if res and (not maxDist or resDist <= maxDist) then
+    return bestValue, bestScore, bestIndex
-        return res, resDist
+end
+
+---
+-- Computes `scoreFn` for each element of `array` and filters out elements with false and nil results.
+-- @function [parent=#util] mapFilter
+-- @param #table array Any array
+-- @param #function scoreFn Filter function
+-- @return #table Output array
+-- @return #table Array of the same size with corresponding scores
+-- @usage -- Find all NPCs in `nearby.actors`
+-- local NPCs = aux_util.mapFilter(
+--     nearby.actors,
+--     function(actor) return actor.type == types.NPC end)
+function aux_util.mapFilter(array, scoreFn)
+    local res = {}
+    local scores = {}
+    for i = 1, #array do
+        local v = array[i]
+        local f = scoreFn(v)
+        if f then
+            scores[#res + 1] = f
+            res[#res + 1] = v
+        end
     end
+    return res, scores
+end
+
+---
+-- Filters and sorts `array` by the scores calculated by `scoreFn`. The same as `aux_util.mapFilter`, but the result is sorted.
+-- @function [parent=#util] mapFilterSort
+-- @param #table array Any array
+-- @param #function scoreFn Filter function
+-- @return #table Output array
+-- @return #table Array of the same size with corresponding scores
+-- @usage -- Find all NPCs in `nearby.actors` and sort them by distances
+-- local NPCs, distances = aux_util.mapFilterSort(
+--     nearby.actors,
+--     function(actor)
+--         return actor.type == types.NPC and (self.position - actor.position):length()
+--     end)
+function aux_util.mapFilterSort(array, scoreFn)
+    local values, scores = aux_util.mapFilter(array, scoreFn)
+    local size = #values
+    local ids = {}
+    for i = 1, size do ids[i] = i end
+    table.sort(ids, function(i, j) return scores[i] < scores[j] end)
+    local sortedValues = {}
+    local sortedScores = {}
+    for i = 1, size do
+        sortedValues[i] = values[ids[i]]
+        sortedScores[i] = scores[ids[i]]
+    end
+    return sortedValues, sortedScores
 end
 
 return aux_util