feat: add SociableNumber implementation

Author: Rosander0

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

@@ -0,0 +1,66 @@
+package com.thealgorithms.maths;
+
+/**
+ * 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
+    }
+
+    /**
+     * Calculates the sum of proper divisors of a number
+     * (all divisors excluding the number itself).
+     *
+     * @param number the number to calculate proper divisors sum for
+     * @return sum of proper divisors, or 0 if number is less than or equal to 0
+     */
+    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.
+     * Starting from the given number, it follows the chain of proper divisor
+     * sums and checks if it returns to the starting number in exactly cycleLength steps.
+     *
+     * @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 && i == cycleLength - 1) {
+                return true;
+            }
+            if (current == number && i != cycleLength - 1) {
+                return false;
+            }
+        }
+        return false;
+    }
+}

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

@@ -0,0 +1,50 @@
+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 forms a cycle of length 2, asking for length 5 hits early return
+        assertFalse(SociableNumber.isSociable(220, 5));
+        assertFalse(SociableNumber.isSociable(284, 3));
+    }
+
+    @Test
+    public void testInvalidInputs() {
+        assertFalse(SociableNumber.isSociable(0, 5));
+        assertFalse(SociableNumber.isSociable(-1, 5));
+        assertFalse(SociableNumber.isSociable(220, 1));
+    }
+}