introducing the requirePowerOfTwoCheck

Signed-off-by: Atanas Atanasov <[email protected]>
hashgraph · Nov 11, 2024 · d0b8434 · d0b8434
1 parent b45127a
commit d0b8434
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 4 deletions.
diff --git a/common/src/main/java/com/hedera/block/common/utils/MathUtilities.java b/common/src/main/java/com/hedera/block/common/utils/MathUtilities.java
@@ -27,6 +27,10 @@ public final class MathUtilities {
      * @return {@code true} if the given number is a power of two
      */
     public static boolean isPowerOfTwo(final int toCheck) {
+        // mathematically powers of two are always positive numbers, so if the
+        // input is negative or zero, it is not a power of two, and we do not
+        // need to trigger the second check, hence we return false immediately
+        // by short-circuiting the logical AND operation
         return (0 < toCheck) && ((toCheck & (toCheck - 1)) == 0);
     }
 }
diff --git a/common/src/main/java/com/hedera/block/common/utils/Preconditions.java b/common/src/main/java/com/hedera/block/common/utils/Preconditions.java
@@ -40,8 +40,8 @@ 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.
+     * This method asserts a given integer is a positive. An integer 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
@@ -50,9 +50,27 @@ public static String requireNotBlank(final String toCheck) {
      */
     public static int requirePositive(final int toCheck) {
         if (0 >= toCheck) {
-            throw new IllegalArgumentException("The input number [%d] is required be positive.".formatted(toCheck));
+            throw new IllegalArgumentException("The input integer [%d] is required be positive.".formatted(toCheck));
+        } else {
+            return toCheck;
+        }
+    }
+
+    /**
+     * This method asserts a given integer is a power of two.
+     *
+     * @param toCheck the number to check if it is a power of two
+     * @return the number to check if it is a power of two
+     * @throws IllegalArgumentException if the input number to check is not a
+     * power of two
+     */
+    public static int requirePowerOfTwo(final int toCheck) {
+        if (!MathUtilities.isPowerOfTwo(toCheck)) {
+            throw new IllegalArgumentException(
+                    "The input integer [%d] is required to be a power of two.".formatted(toCheck));
+        } else {
+            return toCheck;
         }
-        return toCheck;
     }
 
     private Preconditions() {}

diff --git a/common/src/test/java/com/hedera/block/common/CommonsTestUtility.java b/common/src/test/java/com/hedera/block/common/CommonsTestUtility.java
@@ -65,6 +65,9 @@ public static Stream<Arguments> blankStrings() {
                 );
     }
 
+    /**
+     * Some valid power of two integers.
+     */
     public static Stream<Arguments> powerOfTwoIntegers() {
         return Stream.of(
                 Arguments.of(1),
@@ -100,6 +103,9 @@ public static Stream<Arguments> powerOfTwoIntegers() {
                 Arguments.of(1_073_741_824));
     }
 
+    /**
+     * Some power of two integers, but with negative sign.
+     */
     public static Stream<Arguments> negativePowerOfTwoIntegers() {
         return Stream.of(
                 Arguments.of(-1),
@@ -135,6 +141,9 @@ public static Stream<Arguments> negativePowerOfTwoIntegers() {
                 Arguments.of(-1_073_741_824));
     }
 
+    /**
+     * Some non power of two integers.
+     */
     public static Stream<Arguments> nonPowerOfTwoIntegers() {
         return Stream.of(
                 Arguments.of(0),
@@ -155,6 +164,9 @@ public static Stream<Arguments> nonPowerOfTwoIntegers() {
                 Arguments.of(1_073_741_825));
     }
 
+    /**
+     * Some positive integers.
+     */
     public static Stream<Arguments> positiveIntegers() {
         return Stream.of(
                 Arguments.of(1),
@@ -170,6 +182,9 @@ public static Stream<Arguments> positiveIntegers() {
                 Arguments.of(10_000_000));
     }
 
+    /**
+     * Zero and some negative integers.
+     */
     public static Stream<Arguments> zeroAndNegativeIntegers() {
         return Stream.of(
                 Arguments.of(0),

diff --git a/common/src/test/java/com/hedera/block/common/utils/PreconditionsTest.java b/common/src/test/java/com/hedera/block/common/utils/PreconditionsTest.java
@@ -79,4 +79,34 @@ void testRequirePositivePass(final int toTest) {
     void testRequirePositiveFail(final int toTest) {
         assertThatIllegalArgumentException().isThrownBy(() -> Preconditions.requirePositive(toTest));
     }
+
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requirePowerOfTwo(int)} will return the input
+     * 'toTest' parameter if the power of two check passes.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource("com.hedera.block.common.CommonsTestUtility#powerOfTwoIntegers")
+    void testRequirePowerOfTwoPass(final int toTest) {
+        final int actual = Preconditions.requirePowerOfTwo(toTest);
+        assertThat(actual).isPositive().isEqualTo(toTest);
+    }
+
+    /**
+     * This test aims to verify that the
+     * {@link Preconditions#requirePowerOfTwo(int)} will throw an
+     * {@link IllegalArgumentException} if the power of two check fails.
+     *
+     * @param toTest parameterized, the number to test
+     */
+    @ParameterizedTest
+    @MethodSource({
+        "com.hedera.block.common.CommonsTestUtility#nonPowerOfTwoIntegers",
+        "com.hedera.block.common.CommonsTestUtility#negativePowerOfTwoIntegers"
+    })
+    void testRequirePowerOfTwoFail(final int toTest) {
+        assertThatIllegalArgumentException().isThrownBy(() -> Preconditions.requirePowerOfTwo(toTest));
+    }
 }