Add getNullableCharacterWidth-method (#3)

Author: Chrimle

pom.xml

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

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

@@ -30,6 +30,25 @@ public static BaselineStep builder() {
     return FontMetricsBuilder.newInstance();
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * @param character to get the <strong>width</strong> of.
+   * @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
+   *     {@code null} if the {@code width} cannot be determined.
+   * @throws IllegalArgumentException if {@code fontSize} is negative, or zero.
+   * @since 0.1.0
+   */
+  @Override
+  public Double getNullableCharacterWidth(char character, int fontSize)
+      throws IllegalArgumentException {
+    if (fontSize < 1) throw new IllegalArgumentException("`fontSize` MUST be positive");
+    final var widthMap = fontSizeMap.get(fontSize);
+    if (widthMap == null) return null;
+    return widthMap.get(character);
+  }
+
   /**
    * <em>Builder-class</em> for {@link FontMetrics}-instances.
    *

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

@@ -11,6 +11,42 @@
  */
 public sealed interface IFontMetrics permits FontMetrics {
 
+  /**
+   * Gets the <strong>width</strong> of the given {@code character} and {@code fontSize}. If the
+   * {@code character} is not supported, {@code null} 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 {@code null} 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
+   *     {@code null} 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 Double getNullableCharacterWidth(final Character character, final int fontSize)
+      throws NullPointerException, IllegalArgumentException {
+    return getNullableCharacterWidth(character.charValue(), fontSize);
+  }
+
+  /**
+   * Gets the <strong>width</strong> of the given {@code character} and {@code fontSize}. If the
+   * {@code character} is not supported, {@code null} 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 {@code null} is returned.
+   *
+   * @param character to get the <strong>width</strong> of.
+   * @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
+   *     {@code null} if the {@code width} cannot be determined.
+   * @throws IllegalArgumentException if {@code fontSize} is negative, or zero.
+   * @since 0.1.0
+   */
+  Double getNullableCharacterWidth(final char character, final int fontSize)
+      throws IllegalArgumentException;
+
   /**
    * 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

@@ -72,4 +72,67 @@ void testEmptyBaselineMapThrows() {
       }
     }
   }
+
+  @Nested
+  class GetNullableCharacterWidthTests {
+
+    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.getNullableCharacterWidth(null, 7));
+      }
+
+      @Test
+      void testUnsupportedCharacterReturnsNull() {
+        assertNull(fontMetrics.getNullableCharacterWidth('z', 7));
+      }
+
+      @Test
+      void testSupportedCharacterReturnsExpectedWidth() {
+        assertEquals(42d, fontMetrics.getNullableCharacterWidth('x', 7));
+      }
+    }
+
+    @Nested
+    class FontSizeTests {
+      @ParameterizedTest
+      @ValueSource(ints = {Integer.MIN_VALUE, -42, -7, -1})
+      void testNegativeFontSizeThrowsIAE(final int fontSize) {
+        assertThrows(
+            IllegalArgumentException.class,
+            () -> fontMetrics.getNullableCharacterWidth('x', fontSize));
+      }
+
+      @Test
+      void testZeroFontSizeThrowsIAE() {
+        assertThrows(
+            IllegalArgumentException.class, () -> fontMetrics.getNullableCharacterWidth('x', 0));
+      }
+
+      @ParameterizedTest
+      @ValueSource(ints = {1, 3, 7, 11, 42, Integer.MAX_VALUE})
+      void testPositiveFontSizeDoesNotThrow(final int fontSize) {
+        assertDoesNotThrow(() -> fontMetrics.getNullableCharacterWidth('x', fontSize));
+      }
+
+      @Test
+      void testUnsupportedFontSizeReturnsNull() {
+        assertNull(fontMetrics.getNullableCharacterWidth('x', 11));
+      }
+
+      @Test
+      void testSupportedFontSizeReturnsExpectedWidth() {
+        assertEquals(42d, fontMetrics.getNullableCharacterWidth('x', 7));
+      }
+    }
+  }
 }