Add methods in KiwiPrimitives to parse CharSequence to int

Part of #914

src/main/java/org/kiwiproject/base/KiwiPrimitives.java

@@ -4,6 +4,9 @@
 
 import lombok.experimental.UtilityClass;
 
+import java.util.Optional;
+import java.util.OptionalInt;
+
 /**
  * Static utilities that operate on primitive values, and are not already provided by classes in Guava's
  * {@link com.google.common.primitives} package.
@@ -41,4 +44,47 @@ private static long checkNonZero(long value) {
         checkArgument(value != 0, "One of the arguments must be non-zero");
         return value;
     }
+
+    /**
+     * Attempt to parse the given {@link CharSequence} to an {@link Integer}.
+     *
+     * @param cs the value to parse
+     * @return the value as an Integer or {@code null} if the value cannot be parsed
+     */
+    public static Integer tryParseIntOrNull(CharSequence cs) {
+        try {
+            return Integer.valueOf(cs.toString());
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * Attempt to parse the given {@link CharSequence} to an {@code int}.
+     *
+     * @param cs the value to parse
+     * @return an {@link OptionalInt} that will contain the parsed value or will be empty if the input cannot be parsed
+     */
+    public static OptionalInt tryParseInt(CharSequence cs) {
+        try {
+            return OptionalInt.of(Integer.parseInt(cs.toString()));
+        } catch (Exception e) {
+            return OptionalInt.empty();
+        }
+    }
+
+    /**
+     * Attempt to parse the given {@link CharSequence} to an {@code int}/
+     *
+     * @param cs the value to parse
+     * @return the parsed {@code int} value if successful; if it cannot be parsed this method always throws an exception
+     * @throws IllegalStateException if the value cannot be parsed
+     */
+    public static int tryParseIntOrThrow(CharSequence cs) {
+        try {
+            return Integer.parseInt(cs.toString());
+        } catch (Exception e) {
+            throw new IllegalStateException(e);
+        }
+    }
 }

src/test/java/org/kiwiproject/base/KiwiPrimitivesTest.java

@@ -1,10 +1,19 @@
 package org.kiwiproject.base;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
+
 import org.assertj.core.api.SoftAssertions;
 import org.assertj.core.api.junit.jupiter.SoftAssertionsExtension;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
 
+@DisplayName("KiwiPrimitives")
 @ExtendWith(SoftAssertionsExtension.class)
 class KiwiPrimitivesTest {
 
@@ -25,4 +34,72 @@ void testFirstNonZero_Long(SoftAssertions softly) {
         softly.assertThatThrownBy(() -> KiwiPrimitives.firstNonZero(0L, 0L))
                 .isExactlyInstanceOf(IllegalArgumentException.class);
     }
-}
+
+    @Nested
+    class TryParseIntOrNull {
+
+        @Test
+        void shouldReturnInteger_WhenArgumentIsParseableToInt() {
+            assertThat(KiwiPrimitives.tryParseIntOrNull("42")).isEqualTo(42);
+        }
+
+        @ParameterizedTest
+        @NullAndEmptySource
+        void shouldReturnNull_WhenArgumentIsNullOrEmpty(String string) {
+            assertThat(KiwiPrimitives.tryParseIntOrNull(string)).isNull();
+        }
+
+        @ParameterizedTest
+        @ValueSource(strings = {" ", "abcd", "42a", "a42", "4,200", "420.0"})
+        void shouldReturnNull_WhenArgumentIsNotParseableToInt(String string) {
+            assertThat(KiwiPrimitives.tryParseIntOrNull(string)).isNull();
+        }
+    }
+
+    @Nested
+    class TryParseInt {
+
+        @Test
+        void shouldReturnOptionalHavingValue_WhenArgumentIsParseableToInt() {
+            assertThat(KiwiPrimitives.tryParseInt("84")).hasValue(84);
+        }
+
+        @ParameterizedTest
+        @NullAndEmptySource
+        void shouldReturnEmptyOptional_WhenArgumentIsNulOrEmpty(String string) {
+            assertThat(KiwiPrimitives.tryParseInt(string)).isEmpty();
+        }
+
+        @ParameterizedTest
+        @ValueSource(strings = {" ", "abcd", "42a", "a42", "4,200", "420.0"})
+        void shouldReturnEmptyOptional_WhenArgumentIsNotParseableToInt(String string) {
+            assertThat(KiwiPrimitives.tryParseInt(string)).isEmpty();
+        }
+    }
+
+    @Nested
+    class TryParseIntOrThrow {
+
+        @Test
+        void shouldReturInt_WhenArgumentIsParseableToInt() {
+            assertThat(KiwiPrimitives.tryParseIntOrThrow("126")).isEqualTo(126);
+        }
+
+        @Test
+        void shouldThrow_WhenArgumentIsNull() {
+            assertThatIllegalStateException()
+                    .isThrownBy(() -> KiwiPrimitives.tryParseIntOrThrow(null))
+                    .withMessage("java.lang.NullPointerException")
+                    .withCauseExactlyInstanceOf(NullPointerException.class);
+        }
+
+        @ParameterizedTest
+        @ValueSource(strings = {"", " ", "abcd", "42a", "a42", "4,200", "420.0"})
+        void shouldThrow_WhenArgumentIsNotParseableToInt(String string) {
+            assertThatIllegalStateException()
+                    .isThrownBy(() -> KiwiPrimitives.tryParseIntOrThrow(string))
+                    .withMessageContaining(string)
+                    .withCauseExactlyInstanceOf(NumberFormatException.class);
+        }
+    }
+}