introducing the requirePositive precondition and the isPowerOfTwo int…

…eger check

Signed-off-by: Atanas Atanasov <[email protected]>

common/src/main/java/com/hedera/block/common/utils/MathUtilities.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.block.common.utils;
+
+/**
+ * A utility class that deals with logic related to Mathematics.
+ */
+public final class MathUtilities {
+    /**
+     * This method checks if the given number is a power of two.
+     *
+     * @param toCheck the number to check if it is a power of two
+     * @return {@code true} if the given number is a power of two
+     */
+    public static boolean isPowerOfTwo(final int toCheck) {
+        return (0 < toCheck) && ((toCheck & (toCheck - 1)) == 0);
+    }
+}

common/src/main/java/com/hedera/block/common/utils/Preconditions.java

@@ -39,5 +39,21 @@ public static String requireNotBlank(final String toCheck) {
         }
     }
 
+    /**
+     * This method asserts a given number is a positive. A number is positive if
+     * it is NOT equal to zero and is greater than zero.
+     *
+     * @param toCheck the number to check if it is a positive power of two
+     * @return the number to check if it is positive
+     * @throws IllegalArgumentException if the input number to check is not
+     * positive
+     */
+    public static int requirePositive(final int toCheck) {
+        if (0 >= toCheck) {
+            throw new IllegalArgumentException("The input number [%d] is required be positive.".formatted(toCheck));
+        }
+        return toCheck;
+    }
+
     private Preconditions() {}
 }

common/src/test/java/com/hedera/block/common/CommonsTestUtility.java

@@ -65,5 +65,126 @@ public static Stream<Arguments> blankStrings() {
                 );
     }
 
+    public static Stream<Arguments> powerOfTwoIntegers() {
+        return Stream.of(
+                Arguments.of(1),
+                Arguments.of(2),
+                Arguments.of(4),
+                Arguments.of(8),
+                Arguments.of(16),
+                Arguments.of(32),
+                Arguments.of(64),
+                Arguments.of(128),
+                Arguments.of(256),
+                Arguments.of(512),
+                Arguments.of(1_024),
+                Arguments.of(2_048),
+                Arguments.of(4_096),
+                Arguments.of(8_192),
+                Arguments.of(16_384),
+                Arguments.of(32_768),
+                Arguments.of(65_536),
+                Arguments.of(131_072),
+                Arguments.of(262_144),
+                Arguments.of(524_288),
+                Arguments.of(1_048_576),
+                Arguments.of(2_097_152),
+                Arguments.of(4_194_304),
+                Arguments.of(8_388_608),
+                Arguments.of(16_777_216),
+                Arguments.of(33_554_432),
+                Arguments.of(67_108_864),
+                Arguments.of(134_217_728),
+                Arguments.of(268_435_456),
+                Arguments.of(536_870_912),
+                Arguments.of(1_073_741_824));
+    }
+
+    public static Stream<Arguments> negativePowerOfTwoIntegers() {
+        return Stream.of(
+                Arguments.of(-1),
+                Arguments.of(-2),
+                Arguments.of(-4),
+                Arguments.of(-8),
+                Arguments.of(-16),
+                Arguments.of(-32),
+                Arguments.of(-64),
+                Arguments.of(-128),
+                Arguments.of(-256),
+                Arguments.of(-512),
+                Arguments.of(-1_024),
+                Arguments.of(-2_048),
+                Arguments.of(-4_096),
+                Arguments.of(-8_192),
+                Arguments.of(-16_384),
+                Arguments.of(-32_768),
+                Arguments.of(-65_536),
+                Arguments.of(-131_072),
+                Arguments.of(-262_144),
+                Arguments.of(-524_288),
+                Arguments.of(-1_048_576),
+                Arguments.of(-2_097_152),
+                Arguments.of(-4_194_304),
+                Arguments.of(-8_388_608),
+                Arguments.of(-16_777_216),
+                Arguments.of(-33_554_432),
+                Arguments.of(-67_108_864),
+                Arguments.of(-134_217_728),
+                Arguments.of(-268_435_456),
+                Arguments.of(-536_870_912),
+                Arguments.of(-1_073_741_824));
+    }
+
+    public static Stream<Arguments> nonPowerOfTwoIntegers() {
+        return Stream.of(
+                Arguments.of(0),
+                Arguments.of(3),
+                Arguments.of(5),
+                Arguments.of(6),
+                Arguments.of(7),
+                Arguments.of(9),
+                Arguments.of(10),
+                Arguments.of(11),
+                Arguments.of(511),
+                Arguments.of(1_023),
+                Arguments.of(4_097),
+                Arguments.of(16_381),
+                Arguments.of(65_535),
+                Arguments.of(524_287),
+                Arguments.of(33_554_431),
+                Arguments.of(1_073_741_825));
+    }
+
+    public static Stream<Arguments> positiveIntegers() {
+        return Stream.of(
+                Arguments.of(1),
+                Arguments.of(2),
+                Arguments.of(3),
+                Arguments.of(4),
+                Arguments.of(5),
+                Arguments.of(100),
+                Arguments.of(1_000),
+                Arguments.of(10_000),
+                Arguments.of(100_000),
+                Arguments.of(1_000_000),
+                Arguments.of(10_000_000));
+    }
+
+    public static Stream<Arguments> zeroAndNegativeIntegers() {
+        return Stream.of(
+                Arguments.of(0),
+                Arguments.of(-1),
+                Arguments.of(-2),
+                Arguments.of(-3),
+                Arguments.of(-4),
+                Arguments.of(-5),
+                Arguments.of(-100),
+                Arguments.of(-1_000),
+                Arguments.of(-10_000),
+                Arguments.of(-100_000),
+                Arguments.of(-1_000_000),
+                Arguments.of(-10_000_000));
+    }
+
     private CommonsTestUtility() {}
 }

common/src/test/java/com/hedera/block/common/utils/MathUtilitiesTest.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.block.common.utils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+/**
+ * Tests for {@link MathUtilities} functionality.
+ */
+class MathUtilitiesTest {
+    /**
+     * This test aims to verify that the {@link MathUtilities#isPowerOfTwo(int)}
+     * returns {@code true} if the input number is a power of two.
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#powerOfTwoIntegers")
+    void testIsPowerOfTwoPass(final int toTest) {
+        final boolean actual = MathUtilities.isPowerOfTwo(toTest);
+        assertThat(actual).isTrue();
+    }
+
+    /**
+     * This test aims to verify that the {@link MathUtilities#isPowerOfTwo(int)}
+     * returns {@code false} if the input number is not a power of two.
+     */
+    @ParameterizedTest
+    @MethodSource({
+        "com.hedera.block.common.CommonsTestUtility#nonPowerOfTwoIntegers",
+        "com.hedera.block.common.CommonsTestUtility#negativePowerOfTwoIntegers"
+    })
+    void testIsPowerOfTwoFail(final int toTest) {
+        final boolean actual = MathUtilities.isPowerOfTwo(toTest);
+        assertThat(actual).isFalse();
+    }
+}

common/src/test/java/com/hedera/block/common/utils/PreconditionsTest.java

@@ -17,7 +17,7 @@
 package com.hedera.block.common.utils;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
 
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.MethodSource;
@@ -50,7 +50,33 @@ void testRequireNotBlankPass(final String toTest) {
     @ParameterizedTest
     @MethodSource("com.hedera.block.common.CommonsTestUtility#blankStrings")
     void testRequireNotBlankFail(final String toTest) {
-        assertThatExceptionOfType(IllegalArgumentException.class)
-                .isThrownBy(() -> Preconditions.requireNotBlank(toTest));
+        assertThatIllegalArgumentException().isThrownBy(() -> Preconditions.requireNotBlank(toTest));
+    }
+
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requirePositive(int)} will return the input 'toTest'
+     * parameter if the positive check passes.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#positiveIntegers")
+    void testRequirePositivePass(final int toTest) {
+        final int actual = Preconditions.requirePositive(toTest);
+        assertThat(actual).isPositive().isEqualTo(toTest);
+    }
+
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requirePositive(int)} will throw an
+     * {@link IllegalArgumentException} if the positive check fails.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#zeroAndNegativeIntegers")
+    void testRequirePositiveFail(final int toTest) {
+        assertThatIllegalArgumentException().isThrownBy(() -> Preconditions.requirePositive(toTest));
     }
 }