Add modular inverse (#13)

Author: vil02

.spec/math/modular_inverse_spec.lua

@@ -0,0 +1,30 @@
+describe("Modular inverse", function()
+	local modular_inverse = require("math.modular_inverse")
+
+	it("should handle general cases", function()
+		assert.equal(5, modular_inverse(3, 7))
+		assert.equal(4, modular_inverse(-1, 5))
+		assert.equal(4, modular_inverse(4, 5))
+		assert.equal(4, modular_inverse(9, 5))
+		assert.equal(17, modular_inverse(5, 21))
+		assert.equal(1, modular_inverse(1, 100))
+	end)
+
+	it("should handle cases when inputs are not co-prime", function()
+		assert.equal(nil, modular_inverse(2, 2))
+		assert.equal(nil, modular_inverse(5, 15))
+		assert.equal(nil, modular_inverse(0, 1))
+	end)
+
+	it("should throw error when modulus is zero", function()
+		assert.has_error(function()
+			modular_inverse(1, 0)
+		end)
+	end)
+
+	it("should throw error when modulus is negative", function()
+		assert.has_error(function()
+			modular_inverse(1, -1)
+		end)
+	end)
+end)

src/math/modular_inverse.lua

@@ -0,0 +1,17 @@
+local extended_gcd = require("math.greatest_common_divisor")
+
+-- Computes the inverse of `a` modulo `m`, i.e.
+-- finds a number `x` such that
+-- (a * x) % m == 1 and 0 < x < m
+return function(
+	a, -- number
+	m -- modulus
+)
+	assert(m > 0, "modulus must be positive")
+	local gcd, x, _ = extended_gcd(a % m, m)
+	if a ~= 0 and gcd == 1 then
+		-- Ensure that result is in (0, m)
+		return x % m
+	end
+	return nil
+end