feat: add SociableNumber implementation

Author: Rosander0

src/main/java/com/thealgorithms/maths/SociableNumber.java

@@ -0,0 +1,54 @@
+package com.thealgorithms.maths;
+// author: Vraj Prajapati @Rosander0
+
+/**
+ * Sociable numbers are natural numbers that form a cyclic sequence where the
+ * sum of proper divisors of each number equals the next number in the sequence,
+ * with the sequence eventually returning to the starting number.
+ * Amicable numbers are a special case of sociable numbers with a cycle length of 2.
+ * Example: (12496, 14288, 15472, 14536, 14264) is a sociable cycle of length 5.
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Sociable_number">
+ *     Wikipedia: Sociable Number</a>
+ * @see AmicableNumber
+ */
+public final class SociableNumber {
+
+    private SociableNumber() {
+        // Utility class
+    }
+
+    static int sumOfProperDivisors(final int number) {
+        if (number <= 0) {
+            return 0;
+        }
+        int sum = 0;
+        for (int i = 1; i < number; i++) {
+            if (number % i == 0) {
+                sum += i;
+            }
+        }
+        return sum;
+    }
+
+    /**
+     * Checks whether a number is part of a sociable cycle of a given length.
+     *
+     * @param number the starting number (must be positive)
+     * @param cycleLength the expected cycle length (must be greater than 1)
+     * @return true if the number is part of a sociable cycle of given length, false otherwise
+     */
+    public static boolean isSociable(final int number, final int cycleLength) {
+        if (number <= 0 || cycleLength <= 1) {
+            return false;
+        }
+        int current = number;
+        for (int i = 0; i < cycleLength; i++) {
+            current = sumOfProperDivisors(current);
+            if (current == number) {
+                return i == cycleLength - 1;
+            }
+        }
+        return false;
+    }
+}

src/test/java/com/thealgorithms/maths/SociableNumberTest.java

@@ -0,0 +1,52 @@
+package com.thealgorithms.maths;
+// author: Vraj Prajapati @Rosander0
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+public class SociableNumberTest {
+
+    @Test
+    public void testSumOfProperDivisorsEdgeCases() {
+        assertEquals(0, SociableNumber.sumOfProperDivisors(0));
+        assertEquals(0, SociableNumber.sumOfProperDivisors(-5));
+        assertEquals(0, SociableNumber.sumOfProperDivisors(1));
+        assertEquals(1, SociableNumber.sumOfProperDivisors(2));
+    }
+
+    @Test
+    public void testSociableCycleOfLengthFive() {
+        assertTrue(SociableNumber.isSociable(12496, 5));
+    }
+
+    @Test
+    public void testAmicableNumbersAreSociableOfLengthTwo() {
+        assertTrue(SociableNumber.isSociable(220, 2));
+        assertTrue(SociableNumber.isSociable(284, 2));
+    }
+
+    @Test
+    public void testNonSociableNumbers() {
+        assertFalse(SociableNumber.isSociable(12, 5));
+        assertFalse(SociableNumber.isSociable(10, 3));
+    }
+
+    @Test
+    public void testEarlyCycleReturn() {
+        // 220 has cycle length 2, asking for length 3 hits line 60
+        // because current returns to 220 at step 2, but cycleLength-1 = 2 != 1
+        assertFalse(SociableNumber.isSociable(220, 3));
+        assertFalse(SociableNumber.isSociable(284, 4));
+        assertFalse(SociableNumber.isSociable(12496, 3));
+    }
+
+    @Test
+    public void testInvalidInputs() {
+        assertFalse(SociableNumber.isSociable(0, 5));
+        assertFalse(SociableNumber.isSociable(-1, 5));
+        assertFalse(SociableNumber.isSociable(220, 1));
+    }
+}