Add getOptionalCharacterWidth-method (#4)

Author: Chrimle

pom.xml

@@ -7,7 +7,7 @@
     <!-- === Project Coordinates === -->
     <groupId>io.github.chrimle</groupId>
     <artifactId>fontmeter</artifactId>
-    <version>0.1.0-alpha.2</version>
+    <version>0.1.0-alpha.3</version>
     <packaging>jar</packaging>
 
     <!-- === Project Metadata === -->

src/main/java/io/github/chrimle/fontmeter/fonts/IFontMetrics.java

@@ -1,6 +1,7 @@
 package io.github.chrimle.fontmeter.fonts;
 
 import java.util.Map;
+import java.util.Optional;
 
 /**
  * Just an abstraction-layer for {@link FontMetrics}. Contains the interfaces for the {@link
@@ -47,6 +48,46 @@ default Double getNullableCharacterWidth(final Character character, final int fo
   Double getNullableCharacterWidth(final char character, final int fontSize)
       throws IllegalArgumentException;
 
+  /**
+   * Gets the <strong>width</strong> of the given {@code character} and {@code fontSize}. If the
+   * {@code character} is not supported, {@link Optional#empty()} is returned. if the
+   * <strong>width</strong> cannot be determined, by not having it pre-calculated, or if <em>this
+   * instance</em> does not support "on-demand" calculations, then {@link Optional#empty()} is
+   * returned.
+   *
+   * @param character to get the <strong>width</strong> of. <strong>MUST NOT</strong> be {@code
+   *     null}.
+   * @param fontSize of the {@code character}. <strong>MUST</strong> be positive.
+   * @return the width of the {@code character}, in <em>points (pt)</em>. <strong>MAY</strong> be
+   *     {@link Optional#empty()} if the {@code width} cannot be determined.
+   * @throws NullPointerException if {@code character} is {@code null}.
+   * @throws IllegalArgumentException if {@code fontSize} is negative, or zero.
+   * @since 0.1.0
+   */
+  default Optional<Double> getOptionalCharacterWidth(
+      final Character character, final int fontSize) {
+    return getOptionalCharacterWidth(character.charValue(), fontSize);
+  }
+
+  /**
+   * Gets the <strong>width</strong> of the given {@code character} and {@code fontSize}. If the
+   * {@code character} is not supported, {@link Optional#empty()} is returned. if the
+   * <strong>width</strong> cannot be determined, by not having it pre-calculated, or if <em>this
+   * instance</em> does not support "on-demand" calculations, then {@link Optional#empty()} is
+   * returned.
+   *
+   * @param character to get the <strong>width</strong> of. <strong>MUST NOT</strong> be {@code
+   *     null}.
+   * @param fontSize of the {@code character}. <strong>MUST</strong> be positive.
+   * @return the width of the {@code character}, in <em>points (pt)</em>. <strong>MAY</strong> be
+   *     {@link Optional#empty()} if the {@code width} cannot be determined.
+   * @throws IllegalArgumentException if {@code fontSize} is negative, or zero.
+   * @since 0.1.0
+   */
+  default Optional<Double> getOptionalCharacterWidth(final char character, final int fontSize) {
+    return Optional.ofNullable(getNullableCharacterWidth(character, fontSize));
+  }
+
   /**
    * The <em>Builder</em>-step for configuring the <em>baseline</em> for {@link IFontMetrics}. The
    * <em>baseline</em> is a {@link Map} of supported {@link Character}s and their respective

src/test/java/io/github/chrimle/fontmeter/fonts/FontMetricsTest.java

@@ -135,4 +135,67 @@ void testSupportedFontSizeReturnsExpectedWidth() {
       }
     }
   }
+
+  @Nested
+  class GetOptionalCharacterWidthTests {
+
+    private final IFontMetrics fontMetrics =
+        FontMetrics.builder()
+            .setBaseline(7, Map.of('x', 42d))
+            .skipPreCalculation()
+            .disableOnDemandCalculations()
+            .build();
+
+    @Nested
+    class CharacterTests {
+      @Test
+      void testNullCharacterThrowsNPE() {
+        assertThrows(
+            NullPointerException.class, () -> fontMetrics.getOptionalCharacterWidth(null, 7));
+      }
+
+      @Test
+      void testUnsupportedCharacterReturnsEmpty() {
+        assertTrue(fontMetrics.getOptionalCharacterWidth('z', 7).isEmpty());
+      }
+
+      @Test
+      void testSupportedCharacterReturnsExpectedWidth() {
+        assertEquals(42d, fontMetrics.getOptionalCharacterWidth('x', 7).orElseThrow());
+      }
+    }
+
+    @Nested
+    class FontSizeTests {
+      @ParameterizedTest
+      @ValueSource(ints = {Integer.MIN_VALUE, -42, -7, -1})
+      void testNegativeFontSizeThrowsIAE(final int fontSize) {
+        assertThrows(
+            IllegalArgumentException.class,
+            () -> fontMetrics.getOptionalCharacterWidth('x', fontSize));
+      }
+
+      @Test
+      void testZeroFontSizeThrowsIAE() {
+        assertThrows(
+            IllegalArgumentException.class, () -> fontMetrics.getOptionalCharacterWidth('x', 0));
+      }
+
+      @ParameterizedTest
+      @ValueSource(ints = {1, 3, 7, 11, 42, Integer.MAX_VALUE})
+      void testPositiveFontSizeDoesNotThrow(final int fontSize) {
+        assertDoesNotThrow(() -> fontMetrics.getOptionalCharacterWidth('x', fontSize));
+      }
+
+      @Test
+      void testUnsupportedFontSizeReturnsEmpty() {
+        assertTrue(fontMetrics.getOptionalCharacterWidth('x', 11).isEmpty());
+      }
+
+      @Test
+      void testSupportedFontSizeReturnsExpectedWidth() {
+        assertEquals(42d, fontMetrics.getOptionalCharacterWidth('x', 7).orElseThrow());
+      }
+    }
+  }
 }