feat: implement date/time and integer formatting functions (#659)

Implement the XPath 3.1 date/time and integer formatting functions per
the W3C XPath Functions 3.1 specification (sections 4.6.1 and 9.8).

Functions added:
- fn:format-integer with 2-arg and 3-arg signatures supporting decimal
  digit patterns, Roman numerals (i/I), alphabetic (a/A), words (w/W/Ww),
  ordinal numbers, and grouping separators
- fn:format-dateTime with 2-arg and 5-arg signatures
- fn:format-date with 2-arg and 5-arg signatures
- fn:format-time with 2-arg and 5-arg signatures

Key capabilities:
- Picture string parser supporting all 16 component specifiers (Y, M, D,
  d, F, W, w, H, h, P, m, s, f, Z, z, C, E) with presentation modifiers
  and width modifiers
- Formatting engine with year modulo, fractional seconds, timezone
  (numeric, military, GMT prefix), named months/days, and ordinal support
- Proper marker validation per value type (FOFD1350 for invalid markers)
- Ordinal modifier falls back to cardinal for non-decimal format tokens
- Safe Math.abs handling for Integer.MIN_VALUE year values
- FormatFunctionException (FODF1310) and FormatDateTimeFunctionException
  (FOFD1340, FOFD1350) error classes

Includes PRD documentation and 206 unit tests.

Closes #283

Author: david-waltermire

.claude/CLAUDE.md

@@ -191,6 +191,7 @@ For larger initiatives, use PRDs stored in `PRDs/<YYYYMMDD>-<name>/`:
 | PRD | Description | Status |
 |-----|-------------|--------|
 | `PRDs/20251206-build-cleanup/` | Build warnings and deprecation removal | In Progress |
+| `PRDs/20260207-format-datetime/` | Date/time formatting functions (issue #283) | In Progress |
 
 ### Completed PRDs
 

PRDs/20260207-format-datetime/PRD.md

@@ -0,0 +1,81 @@
+/*
+ * SPDX-FileCopyrightText: none
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+package dev.metaschema.core.metapath.function;
+
+import dev.metaschema.core.metapath.IErrorCode;
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+/**
+ * FOFD: Exceptions related to errors in formatting date/time values.
+ *
+ * @see <a href="https://www.w3.org/TR/xpath-functions-31/#formatting-dates">
+ *      XPath Functions 3.1 - Formatting Dates and Times</a>
+ */
+public class FormatDateTimeFunctionException
+    extends FunctionMetapathError {
+  @NonNull
+  private static final String PREFIX = "FOFD";
+  /**
+   * <a href=
+   * "https://www.w3.org/TR/xpath-functions-31/#ERRFOFD1340">err:FOFD1340</a>:
+   * Raised when the picture string supplied to a date/time formatting function
+   * does not conform to the required syntax.
+   */
+  public static final int INVALID_PICTURE_STRING = 1340;
+  /**
+   * <a href=
+   * "https://www.w3.org/TR/xpath-functions-31/#ERRFOFD1350">err:FOFD1350</a>:
+   * Raised when a component specifier within a picture string refers to a
+   * component that is not available in the value being formatted.
+   */
+  public static final int COMPONENT_NOT_AVAILABLE = 1350;
+
+  /**
+   * the serial version UID.
+   */
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * Constructs a new exception with the provided {@code code}, {@code message},
+   * and no cause.
+   *
+   * @param code
+   *          the error code value
+   * @param message
+   *          the exception message
+   */
+  public FormatDateTimeFunctionException(int code, String message) {
+    super(IErrorCode.of(PREFIX, code), message);
+  }
+
+  /**
+   * Constructs a new exception with the provided {@code code}, {@code message},
+   * and {@code cause}.
+   *
+   * @param code
+   *          the error code value
+   * @param message
+   *          the exception message
+   * @param cause
+   *          the original exception cause
+   */
+  public FormatDateTimeFunctionException(int code, String message, Throwable cause) {
+    super(IErrorCode.of(PREFIX, code), message, cause);
+  }
+
+  /**
+   * Constructs a new exception with the provided {@code code}, no message, and
+   * the {@code cause}.
+   *
+   * @param code
+   *          the error code value
+   * @param cause
+   *          the original exception cause
+   */
+  public FormatDateTimeFunctionException(int code, Throwable cause) {
+    super(IErrorCode.of(PREFIX, code), cause);
+  }
+}

PRDs/20260207-format-datetime/implementation-plan.md

@@ -0,0 +1,72 @@
+/*
+ * SPDX-FileCopyrightText: none
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+package dev.metaschema.core.metapath.function;
+
+import dev.metaschema.core.metapath.IErrorCode;
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+/**
+ * FODF: Exceptions related to formatting errors in Metapath functions such as
+ * {@code format-integer}, {@code format-number}, {@code format-dateTime}, and
+ * {@code format-date}.
+ */
+public class FormatFunctionException
+    extends FunctionMetapathError {
+  @NonNull
+  private static final String PREFIX = "FODF";
+  /**
+   * <a href=
+   * "https://www.w3.org/TR/xpath-functions-31/#ERRFODF1310">err:FODF1310</a>:
+   * Raised when a format token in a picture string is invalid.
+   */
+  public static final int INVALID_FORMAT_TOKEN = 1310;
+
+  /**
+   * the serial version UID.
+   */
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * Constructs a new exception with the provided {@code code}, {@code message},
+   * and no cause.
+   *
+   * @param code
+   *          the error code value
+   * @param message
+   *          the exception message
+   */
+  public FormatFunctionException(int code, String message) {
+    super(IErrorCode.of(PREFIX, code), message);
+  }
+
+  /**
+   * Constructs a new exception with the provided {@code code}, {@code message},
+   * and {@code cause}.
+   *
+   * @param code
+   *          the error code value
+   * @param message
+   *          the exception message
+   * @param cause
+   *          the original exception cause
+   */
+  public FormatFunctionException(int code, String message, Throwable cause) {
+    super(IErrorCode.of(PREFIX, code), message, cause);
+  }
+
+  /**
+   * Constructs a new exception with the provided {@code code}, no message, and
+   * the {@code cause}.
+   *
+   * @param code
+   *          the error code value
+   * @param cause
+   *          the original exception cause
+   */
+  public FormatFunctionException(int code, Throwable cause) {
+    super(IErrorCode.of(PREFIX, code), cause);
+  }
+}