feat: Added a proper Modular Exponentiation algorithm (#275)

* fix: the algorithm handle for go get command

* fix: changed the required import from my repo (tjgurwara99/Go) to the algorithms repo (TheAlgorithms/Go)

* fix: typo

* feat: Global Modular Exponentiation for uses in other files

* fix: updated comment

* updating DIRECTORY.md

* fix: changed the benchmarking for a proper test

* fix: better error handling

* fix: removed unused type struct

Co-authored-by: github-actions <${GITHUB_ACTOR}@users.noreply.github.com>

Author: tjgurwara99

DIRECTORY.md

@@ -69,6 +69,9 @@
   * Gcd
     * [Gcd](https://github.com/TheAlgorithms/Go/blob/master/math/gcd/gcd.go)
     * [Gcd Test](https://github.com/TheAlgorithms/Go/blob/master/math/gcd/gcd_test.go)
+  * Modulararithmetic
+    * [Modularexponentiation](https://github.com/TheAlgorithms/Go/blob/master/math/modulararithmetic/modularexponentiation.go)
+    * [Modularexponentiation Test](https://github.com/TheAlgorithms/Go/blob/master/math/modulararithmetic/modularexponentiation_test.go)
   * Power
     * [Fastexponent](https://github.com/TheAlgorithms/Go/blob/master/math/power/fastexponent.go)
     * [Fastexponent Test](https://github.com/TheAlgorithms/Go/blob/master/math/power/fastexponent_test.go)

math/modulararithmetic/modularexponentiation.go

@@ -0,0 +1,49 @@
+package modulararithmetic
+
+import (
+	"errors"
+	"math"
+)
+
+// ErrorIntOverflow For asserting that the values do not overflow in Int64
+var ErrorIntOverflow = errors.New("Integer Overflow")
+
+// ErrorNegativeExponent for asserting that the exponent we receive is positive
+var ErrorNegativeExponent = errors.New("Negative Exponent Provided")
+
+// ModularExponentiation returns base^exponent % mod
+func ModularExponentiation(base, exponent, mod int64) (int64, error) {
+	if mod == 1 {
+		return 0, nil
+	}
+
+	if exponent < 0 {
+		return -1, ErrorNegativeExponent
+	}
+	_, err := Multiply64BitInt(mod-1, mod-1)
+
+	if err != nil {
+		return -1, err
+	}
+
+	var result int64 = 1
+
+	base = base % mod
+
+	for exponent > 0 {
+		if exponent%2 == 1 {
+			result = (result * base) % mod
+		}
+		exponent = exponent >> 1
+		base = (base * base) % mod
+	}
+	return result, nil
+}
+
+// Multiply64BitInt Checking if the integer multiplication overflows
+func Multiply64BitInt(left, right int64) (int64, error) {
+	if math.Abs(float64(left)) > float64(math.MaxInt64)/math.Abs(float64(right)) {
+		return 0, ErrorIntOverflow
+	}
+	return left * right, nil
+}

math/modulararithmetic/modularexponentiation_test.go

@@ -0,0 +1,84 @@
+package modulararithmetic
+
+import "testing"
+
+type cases struct {
+	name          string
+	description   string
+	base          int64
+	exponent      int64
+	mod           int64
+	expected      int64
+	expectedError error
+}
+
+var testCases = []cases{
+	{
+		name:          "Test 1",
+		description:   "Test 1: 3^6 % 3 == 0",
+		base:          3,
+		exponent:      6,
+		mod:           3,
+		expected:      0,
+		expectedError: nil,
+	},
+	{
+		name:          "Test 2",
+		description:   "Test 2: 33^60 % 25 == 1",
+		base:          33,
+		exponent:      60,
+		mod:           25,
+		expected:      1,
+		expectedError: nil,
+	},
+	{
+		name:          "Test 3",
+		description:   "Test 3: 17^60 % 23 == 2",
+		base:          17,
+		exponent:      60,
+		mod:           23,
+		expected:      2,
+		expectedError: nil,
+	},
+	{
+		name:          "Test 4",
+		description:   "Test 4: 17^60 % 1 == 0", // handling result when we get mod = 1
+		base:          17,
+		exponent:      60,
+		mod:           1,
+		expected:      0,
+		expectedError: nil,
+	},
+	{
+		name:          "Error test 1",
+		description:   "Testing whether we receive the expected errors gracefully",
+		base:          50,
+		exponent:      -1,
+		mod:           2,
+		expected:      -1,
+		expectedError: ErrorNegativeExponent,
+	},
+}
+
+func TestModularExponentiation(t *testing.T) {
+	for _, test := range testCases {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := ModularExponentiation(test.base, test.exponent, test.mod)
+			if err != test.expectedError {
+				t.Logf("Test Failed for %s", test.name)
+				t.Logf("Unexpected error occured")
+				t.Errorf("Expected error: %v, Recieved error: %v", test.expectedError, err)
+			}
+			if result != test.expected {
+				t.Logf("Test Failed for %s", test.description)
+				t.Fatalf("Expected: %d, Recieved: %d", test.expected, result)
+			}
+		})
+	}
+}
+
+func BenchmarkModularExponentiation(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		_, _ = ModularExponentiation(17, 60, 23)
+	}
+}