From 43203a5adf4a6399f40feb243ba0794737bbf8d7 Mon Sep 17 00:00:00 2001
From: Rosander0 <astereen.0107@gmail.com>
Date: Mon, 15 Jun 2026 17:35:44 +0530
Subject: [PATCH] feat: add PerrinNumber implementation

---
 .../com/thealgorithms/maths/PerrinNumber.java | 53 +++++++++++++++++++
 .../thealgorithms/maths/PerrinNumberTest.java | 34 ++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 src/main/java/com/thealgorithms/maths/PerrinNumber.java
 create mode 100644 src/test/java/com/thealgorithms/maths/PerrinNumberTest.java

diff --git a/src/main/java/com/thealgorithms/maths/PerrinNumber.java b/src/main/java/com/thealgorithms/maths/PerrinNumber.java
new file mode 100644
index 000000000000..cee45a1c5538
--- /dev/null
+++ b/src/main/java/com/thealgorithms/maths/PerrinNumber.java
@@ -0,0 +1,53 @@
+package com.thealgorithms.maths;
+// author: Vraj Prajapati @Rosander0
+
+/**
+ * The Perrin Sequence is a sequence of integers defined by the recurrence relation:
+ * P(n) = P(n-2) + P(n-3) with initial values P(0) = 3, P(1) = 0, P(2) = 2.
+ * Example: 3, 0, 2, 3, 2, 5, 5, 7, 10, 12, 17, 22, 29, 39, 51...
+ *
+ * Note: The Perrin Sequence uses the same recurrence relation as the Padovan Sequence
+ * but has different initial values.
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Perrin_number">
+ *     Wikipedia: Perrin Number</a>
+ * @see PadovanSequence
+ */
+public final class PerrinNumber {
+
+    private PerrinNumber() {
+        // Utility class
+    }
+
+    /**
+     * Calculates the nth term of the Perrin Sequence.
+     *
+     * @param n the index of the sequence (must be non-negative)
+     * @return the nth term of the Perrin Sequence
+     */
+    public static long perrin(final int n) {
+        if (n < 0) {
+            throw new IllegalArgumentException("Input must be non-negative!");
+        }
+        if (n == 0) {
+            return 3;
+        }
+        if (n == 1) {
+            return 0;
+        }
+        if (n == 2) {
+            return 2;
+        }
+        long a = 3;
+        long b = 0;
+        long c = 2;
+        long result = 0;
+        for (int i = 3; i <= n; i++) {
+            result = a + b;
+            a = b;
+            b = c;
+            c = result;
+        }
+        return result;
+    }
+}
diff --git a/src/test/java/com/thealgorithms/maths/PerrinNumberTest.java b/src/test/java/com/thealgorithms/maths/PerrinNumberTest.java
new file mode 100644
index 000000000000..0ec476dc0641
--- /dev/null
+++ b/src/test/java/com/thealgorithms/maths/PerrinNumberTest.java
@@ -0,0 +1,34 @@
+package com.thealgorithms.maths;
+// author: Vraj Prajapati @Rosander0
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+public class PerrinNumberTest {
+
+    @Test
+    public void testBaseCases() {
+        assertEquals(3, PerrinNumber.perrin(0));
+        assertEquals(0, PerrinNumber.perrin(1));
+        assertEquals(2, PerrinNumber.perrin(2));
+    }
+
+    @Test
+    public void testKnownValues() {
+        assertEquals(3, PerrinNumber.perrin(3));
+        assertEquals(2, PerrinNumber.perrin(4));
+        assertEquals(5, PerrinNumber.perrin(5));
+        assertEquals(5, PerrinNumber.perrin(6));
+        assertEquals(7, PerrinNumber.perrin(7));
+        assertEquals(10, PerrinNumber.perrin(8));
+        assertEquals(12, PerrinNumber.perrin(9));
+        assertEquals(17, PerrinNumber.perrin(10));
+    }
+
+    @Test
+    public void testInvalidInput() {
+        assertThrows(IllegalArgumentException.class, () -> PerrinNumber.perrin(-1));
+    }
+}