numeric_ops.lua

--- An assortment of useful numeric operations.

--
-- Permission is hereby granted, free of charge, to any person obtaining
-- a copy of this software and associated documentation files (the
-- "Software"), to deal in the Software without restriction, including
-- without limitation the rights to use, copy, modify, merge, publish,
-- distribute, sublicense, and/or sell copies of the Software, and to
-- permit persons to whom the Software is furnished to do so, subject to
-- the following conditions:
--
-- The above copyright notice and this permission notice shall be
-- included in all copies or substantial portions of the Software.
--
-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-- CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--
-- [ MIT license: http://www.opensource.org/licenses/mit-license.php ]
--

-- Standard library imports --
local floor = math.floor
local max = math.max
local min = math.min

-- Exports --
local M = {}

--- Clamps a number between two bounds.
--
-- The bounds are swapped if out of order.
-- @number n Number to clamp.
-- @number minb Minimum bound.
-- @number maxb Maximum bound.
-- @treturn number Clamped number.
function M.ClampIn (n, minb, maxb)
	if minb > maxb then
		minb, maxb = maxb, minb
	end

	return min(max(n, minb), maxb)
end

--- Breaks the result of _a_ / _b_ up into a count and remainder.
-- @number a Dividend.
-- @number b Divisor.
-- @treturn int Number of times that _b_ divides _a_.
-- @treturn number Fractional part of _b_ left over after the integer part is considered.
function M.DivRem (a, b)
	local quot = floor(a / b)

	return quot, a - quot * b
end

---@number a Value #1.
-- @number b Value #2.
-- @treturn number Minimum value.
-- @treturn number Maximum value.
function M.MinMax (a, b)
	return min(a, b), max(a, b)
end

--- Variant of @{MinMax} that contrains its arguments to an interval.
--
-- N.B. As a side effect of clamping, if both _a_ and _b_ are < _m_, or both > _n_,
-- the "maximum" will be < _m_, or the "minimum" > _n_, respectively, i.e. the return
-- values will be out of order.
-- @number a Value #1.
-- @number b Value #2.
-- @number m Range lower bound.
-- @number n Range upper bound, ≥ _m_.
-- @treturn number Clamped minimum value, ∈ [_m_, +∞).
-- @treturn number Clamped maximum value, ∈ (-∞, _n_].
function M.MinMax_Interval (a, b, m, n)
	a, b = M.MinMax(a, b)

	return max(a, m), min(b, n)
end

--- Variant of @{MinMax} that contrains its arguments to a range.
--
-- The return values proviso applies as per @{MinMax_Interval}.
-- @number a Value #1.
-- @number b Value #2.
-- @number n Range limit ≥ 1.
-- @treturn number Clamped minimum value, ∈ [1, +∞).
-- @treturn number Clamped maximum value, ∈ (-∞, _n_].
function M.MinMax_Range (a, b, n)
	a, b = M.MinMax(a, b)

	return max(a, 1), min(b, n)
end

--- Rounds a number to the nearest multiple of some increment.
-- @number n Number to round.
-- @number inc Increment; by default, 1.
-- @treturn number Rounded result.
function M.RoundTo (n, inc)
	inc = inc or 1

	return floor(n / inc + .5) * inc
end

-- Export the module.
return M