[algo] Improve documentation.

This commit is contained in:
Lorenzo Cogotti 2022-09-01 08:52:02 +02:00
parent 018fc77a13
commit 0ce17379a1
1 changed files with 29 additions and 22 deletions

View File

@ -12,16 +12,19 @@ local algo = {}
--- Clamp x within range [a,b] (where b >= a). --- Clamp x within range [a,b] (where b >= a).
-- --
-- @param x (number) value to clamp. -- @number x value to clamp.
-- @param a (number) interval lower bound (inclusive). -- @number a interval lower bound (inclusive).
-- @param b (number) interval upper bound (includive). -- @number b interval upper bound (includive).
-- @return (number) clamped value. -- @treturn number clamped value.
function algo.clamp(x, a, b) return min(max(x, a), b) end function algo.clamp(x, a, b) return min(max(x, a), b) end
--- Fast remove from array. --- Fast remove from array.
-- --
-- Replace 'array[i]' with last array's element and -- Replace 'array[i]' with last array's element and
-- discard array's tail. -- discard array's tail.
--
-- @tparam table array
-- @int i
function algo.removefast(array, i) function algo.removefast(array, i)
local n = #array local n = #array
@ -37,10 +40,11 @@ local function lt(a, b) return a < b end
-- Performs better than regular table.sort() for small arrays -- Performs better than regular table.sort() for small arrays
-- (~100 elements). -- (~100 elements).
-- --
-- @param array (table) array to be sorted. -- @tparam table array array to be sorted.
-- @param less (function|nil) comparison function, takes 2 arguments, -- @tparam[opt=operator <] function less comparison function, takes 2 arguments,
-- returns true if its first argument is less than its second argument, false otherwise. -- returns true if its first argument is
-- Defaults to operator <. -- less than its second argument,
-- false otherwise.
function algo.insertionsort(array, less) function algo.insertionsort(array, less)
less = less or lt less = less or lt
@ -60,13 +64,14 @@ end
--- Binary search last element where --- Binary search last element where
-- what <= array[i] - also known as lower bound. -- what <= array[i] - also known as lower bound.
-- --
-- @param array (table) an array sorted according to the less function. -- @tparam table array an array sorted according to the less function.
-- @param what the comparison argument. -- @param what the comparison argument.
-- @param less (function|nil) sorting criterium, a function taking 2 arguments, -- @tparam[opt=operator <] function less sorting criterium, a function taking 2 arguments,
-- returns true if the first argument is less than the second argument, -- returns true if the first argument
-- false otherwise. Defaults to using the < operator. -- is less than the second argument,
-- false otherwise.
-- --
-- @return (number) the greatest index i, where what <= array[i]. -- @treturn int the greatest index i, where what <= array[i].
-- If no such element exists, it returns an out of bounds index -- If no such element exists, it returns an out of bounds index
-- such that array[i] == nil. -- such that array[i] == nil.
function algo.bsearchl(array, what, less) function algo.bsearchl(array, what, less)
@ -94,13 +99,15 @@ end
--- Binary search first element where --- Binary search first element where
-- what >= array[i] - also known as upper bound. -- what >= array[i] - also known as upper bound.
-- --
-- @param array (array) an array sorted according to the less function. -- @tparam table array an array sorted according to the less function.
-- @param what the comparison argument. -- @param what the comparison argument.
-- @param less (function|nil) sorting criterium, a function taking 2 arguments, -- @tparam[opt=operator <] function less sorting criterium,
-- returns true if the first argument is less than the second argument, -- a function taking 2 arguments,
-- false otherwise. Defaults to using the < operator. -- returns true if the first argument
-- is less than the second argument,
-- false otherwise.
-- --
-- @return (number) the smallest index i, where what >= array[i]. -- @treturn int the smallest index i, where what >= array[i].
-- If no such element exists, it returns an out of bounds index -- If no such element exists, it returns an out of bounds index
-- such that array[i] == nil. -- such that array[i] == nil.
function algo.bsearchr(array, what, less) function algo.bsearchr(array, what, less)