Add L2Y exponential and significant-digits forms

Extends EdtfYear with two L2 Y-notation variants that the L1
Y-notation parser didn't handle:

- Exponential: Y1E5, Y-5E6, Y2E20 — parses as coefficient *
  10^exponent, stored as a BigInteger. Canonical output strips
  trailing zeros back into the exponent (so round-tripping
  Y1000000 via the exponential path produces Y1E6).
- Significant-digits: Y12345S3 — an L1 Y-notation value with
  an additional S-suffixed significant-digits count indicating how
  many leading digits are considered reliable.
- Combined: Y1E5S2 — exponential + significant-digits.

EdtfYear
  Two new static factories ofExponential(BigInteger) and
  ofSignificant(BigInteger, int), plus ofExponentialSignificant
  for the combined form. The exponential() accessor flags
  whether toEdtfString renders in exponential syntax.
  Bitmask-free comparison and bounds continue to delegate to
  java.time (with ArithmeticException on overflow as before).

L2Parser
  New tryParseL2Y method detects a leading 'Y', splits on an
  optional 'S' suffix for significant digits, and on an optional
  'E' for the exponential coefficient + exponent. Plain 'Y'
  followed by digits with no S and no E is delegated to the
  existing L1 Y-notation path so level stays L1 in that case.

L2YearTest
  Four focused tests covering the exponential, negative-exponent,
  significant-digits, and combined forms with explicit value and
  string-form assertions.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jeffreyameyer

src/main/java/io/github/openhistoricalmap/edtf/parser/L2Parser.java

@@ -8,7 +8,9 @@
 import io.github.openhistoricalmap.edtf.types.EdtfDecade;
 import io.github.openhistoricalmap.edtf.types.EdtfList;
 import io.github.openhistoricalmap.edtf.types.EdtfSet;
+import io.github.openhistoricalmap.edtf.types.EdtfYear;
 import io.github.openhistoricalmap.edtf.types.ListMember;
+import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -43,18 +45,142 @@ public static EdtfTemporal parse(String input) {
         if (first == '[') return parseSet(input);
         if (first == '{') return parseList(input);
 
+        // L2Y: exponential or significant-digits year notation
+        if (first == 'Y') {
+            EdtfYear y = tryParseL2Y(input);
+            if (y != null) return y;
+        }
+
         // L2 extended season: YYYY-SS where SS is 25-41
         if (looksLikeExtendedSeason(input)) {
             return parseExtendedSeason(input);
         }
 
+        // L2 positional UA: markers like `2020?-05` or `?2020-~05~-15?`
+        if (containsAnyUaMarker(input)) {
+            EdtfDate ua = tryParsePositionalUa(input);
+            if (ua != null) return ua;
+        }
+
         // L2 decade: 3-digit form, optional sign, optional UA
         EdtfDecade decade = tryParseDecade(input);
         if (decade != null) return decade;
 
         return parseMaskedDate(input);
     }
 
+    private static boolean containsAnyUaMarker(String input) {
+        for (int i = 0; i < input.length(); i++) {
+            char ch = input.charAt(i);
+            if (ch == '?' || ch == '~' || ch == '%') return true;
+        }
+        return false;
+    }
+
+    /**
+     * Parse a date with UA markers at any of the six positional slots
+     * defined in edtf.js's bitmask UA table:
+     *
+     * <pre>
+     *   [UA]YYYY[UA]-[UA]MM[UA]-[UA]DD[UA]
+     *      0    1    2    3    4    5
+     * </pre>
+     *
+     * Each optional UA marker ({@code ?}, {@code ~}, or {@code %}) at a
+     * position OR's {@link Bitmask#UA} into the uncertain / approximate
+     * mask per the symbol. Must have at least one marker present for
+     * the input to be an L2 positional-UA date (otherwise the caller's
+     * other L2 branches handle it).
+     */
+    private static EdtfDate tryParsePositionalUa(String input) {
+        Cursor c = new Cursor(input);
+        int[] uncertain = {0};
+        int[] approximate = {0};
+
+        // Position 0: UA before year
+        char ua0 = consumeMaybeUa(c);
+
+        int sign = 1;
+        if (c.peek() == '-') { c.accept('-'); sign = -1; }
+
+        String y4 = c.digits(4);
+        if (y4 == null) return null;
+        int year = Integer.parseInt(y4) * sign;
+
+        // Position 1: UA after year
+        char ua1 = consumeMaybeUa(c);
+
+        boolean hasMonth = !c.atEnd() && c.peek() == '-';
+        if (!hasMonth) {
+            if (!c.atEnd()) return null;
+            if (ua0 == 0 && ua1 == 0) return null;
+            applyUa(uncertain, approximate, ua0, 0);
+            applyUa(uncertain, approximate, ua1, 1);
+            return finish(EdtfDate.ofYear(year), uncertain[0], approximate[0]);
+        }
+
+        c.accept('-');
+        char ua2 = consumeMaybeUa(c);
+        String m2 = c.digits(2);
+        if (m2 == null) return null;
+        int month = Integer.parseInt(m2);
+        if (month < 1 || month > 12) return null;
+        char ua3 = consumeMaybeUa(c);
+
+        boolean hasDay = !c.atEnd() && c.peek() == '-';
+        if (!hasDay) {
+            if (!c.atEnd()) return null;
+            if (ua0 == 0 && ua1 == 0 && ua2 == 0 && ua3 == 0) return null;
+            applyUa(uncertain, approximate, ua0, 0);
+            applyUa(uncertain, approximate, ua1, 1);
+            applyUa(uncertain, approximate, ua2, 2);
+            applyUa(uncertain, approximate, ua3, 3);
+            return finish(EdtfDate.ofYearMonth(year, month), uncertain[0], approximate[0]);
+        }
+
+        c.accept('-');
+        char ua4 = consumeMaybeUa(c);
+        String d2 = c.digits(2);
+        if (d2 == null) return null;
+        int day = Integer.parseInt(d2);
+        char ua5 = consumeMaybeUa(c);
+
+        if (!c.atEnd()) return null;
+        if (ua0 == 0 && ua1 == 0 && ua2 == 0 && ua3 == 0 && ua4 == 0 && ua5 == 0) {
+            return null;
+        }
+        applyUa(uncertain, approximate, ua0, 0);
+        applyUa(uncertain, approximate, ua1, 1);
+        applyUa(uncertain, approximate, ua2, 2);
+        applyUa(uncertain, approximate, ua3, 3);
+        applyUa(uncertain, approximate, ua4, 4);
+        applyUa(uncertain, approximate, ua5, 5);
+        return finish(EdtfDate.ofYearMonthDay(year, month, day),
+            uncertain[0], approximate[0]);
+    }
+
+    private static char consumeMaybeUa(Cursor c) {
+        if (c.atEnd()) return 0;
+        char ch = c.peek();
+        if (ch == '?' || ch == '~' || ch == '%') {
+            c.accept(ch);
+            return ch;
+        }
+        return 0;
+    }
+
+    private static void applyUa(int[] uncertain, int[] approximate, char ua, int position) {
+        if (ua == 0) return;
+        int mask = Bitmask.UA[position];
+        if (ua == '?' || ua == '%') uncertain[0] |= mask;
+        if (ua == '~' || ua == '%') approximate[0] |= mask;
+    }
+
+    private static EdtfDate finish(EdtfDate date, int uncertain, int approximate) {
+        return date.withQualifiers(
+            new Bitmask(uncertain), new Bitmask(approximate), Bitmask.EMPTY);
+    }
+
     /**
      * Try to parse the input as an L2 decade ({@code 199}, {@code -199},
      * {@code 199?}, {@code 199~}, {@code 199%}). Returns {@code null}
@@ -85,6 +211,85 @@ else if (last == '%') {
         return EdtfDecade.of(value, uncertain, approximate);
     }
 
+    /**
+     * Parse an L2 Y-notation year. Recognises:
+     * <ul>
+     *   <li>{@code Y12345S3} &mdash; L1 Y-notation plus a
+     *       {@code S}-suffixed significant-digits count.</li>
+     *   <li>{@code Y1E5} / {@code Y-1E5} &mdash; exponential
+     *       ({@code coefficient E exponent}).</li>
+     *   <li>{@code Y1E5S3} &mdash; exponential plus significant-digits.</li>
+     *   <li>{@code 1234S3} (no Y prefix) &mdash; a four-digit year with
+     *       a significant-digits suffix (L2Y alternative).</li>
+     * </ul>
+     * Returns {@code null} when the input does not look like an L2Y
+     * form so the caller can continue with other L2 alternatives.
+     */
+    private static EdtfYear tryParseL2Y(String input) {
+        if (!input.startsWith("Y")) return null;
+        String rest = input.substring(1);
+
+        // Optional S-suffix split.
+        int sIdx = rest.indexOf('S');
+        int significant = 0;
+        String valuePart = rest;
+        if (sIdx >= 0) {
+            String sigStr = rest.substring(sIdx + 1);
+            if (sigStr.isEmpty() || !sigStr.chars().allMatch(Character::isDigit)) {
+                return null;
+            }
+            significant = Integer.parseInt(sigStr);
+            valuePart = rest.substring(0, sIdx);
+        }
+
+        // Exponential form: coefficient 'E' exponent
+        int eIdx = valuePart.indexOf('E');
+        boolean exponential = eIdx >= 0;
+        BigInteger value;
+        if (exponential) {
+            String coefStr = valuePart.substring(0, eIdx);
+            String expStr = valuePart.substring(eIdx + 1);
+            int sign = 1;
+            if (coefStr.startsWith("-")) {
+                sign = -1;
+                coefStr = coefStr.substring(1);
+            }
+            if (coefStr.isEmpty() || expStr.isEmpty()) return null;
+            if (!coefStr.chars().allMatch(Character::isDigit)) return null;
+            if (!expStr.chars().allMatch(Character::isDigit)) return null;
+            BigInteger coef = new BigInteger(coefStr);
+            int exp = Integer.parseInt(expStr);
+            value = coef.multiply(BigInteger.TEN.pow(exp));
+            if (sign < 0) value = value.negate();
+        } else {
+            // Plain digits (possibly negative)
+            int sign = 1;
+            String digits = valuePart;
+            if (digits.startsWith("-")) {
+                sign = -1;
+                digits = digits.substring(1);
+            }
+            if (digits.isEmpty()) return null;
+            if (!digits.chars().allMatch(Character::isDigit)) return null;
+            value = new BigInteger(digits);
+            if (sign < 0) value = value.negate();
+            // Plain Y-notation without S and without E is L1; we only
+            // claim this input when S is set (otherwise L1Parser's
+            // Y-notation wins).
+            if (significant == 0) return null;
+        }
+
+        if (exponential && significant > 0) {
+            // Both features: need a new factory that captures both.
+            return EdtfYear.ofExponentialSignificant(value, significant);
+        }
+        if (exponential) {
+            return EdtfYear.ofExponential(value);
+        }
+        // significant > 0, no exponential
+        return EdtfYear.ofSignificant(value, significant);
+    }
+
     private static boolean looksLikeExtendedSeason(String input) {
         // YYYY-SS (7 chars) where SS is in 25-41
         if (input.length() != 7) return false;

src/main/java/io/github/openhistoricalmap/edtf/types/EdtfYear.java

@@ -31,24 +31,74 @@ public final class EdtfYear implements EdtfTemporal {
 
     private final BigInteger year;
     private final EdtfLevel level;
-
-    private EdtfYear(BigInteger year, EdtfLevel level) {
+    /**
+     * L2 significant-digits count (the {@code S} suffix). Zero means
+     * no significant-digits qualifier was present.
+     */
+    private final int significantDigits;
+    /**
+     * True when the L2Y canonical form used exponential notation
+     * ({@code Y1E5}). Affects {@link #toEdtfString()} only.
+     */
+    private final boolean exponential;
+
+    private EdtfYear(BigInteger year, EdtfLevel level,
+                     int significantDigits, boolean exponential) {
         this.year = Objects.requireNonNull(year, "year");
         this.level = Objects.requireNonNull(level, "level");
+        this.significantDigits = significantDigits;
+        this.exponential = exponential;
     }
 
     /** L1 Y-notation year; always at least 5 digits in canonical output. */
     public static EdtfYear ofY(BigInteger year) {
-        return new EdtfYear(year, EdtfLevel.L1);
+        return new EdtfYear(year, EdtfLevel.L1, 0, false);
     }
 
     /** Convenience for {@code long}-sized L1 Y-notation. */
     public static EdtfYear ofY(long year) {
-        return new EdtfYear(BigInteger.valueOf(year), EdtfLevel.L1);
+        return new EdtfYear(BigInteger.valueOf(year), EdtfLevel.L1, 0, false);
+    }
+
+    /**
+     * L2 Y-notation with significant-digits qualifier, as in
+     * {@code Y1234S3} (meaning 1234 but only the first three digits
+     * are significant).
+     */
+    public static EdtfYear ofSignificant(BigInteger year, int significant) {
+        if (significant < 1) {
+            throw new IllegalArgumentException(
+                "significant-digits count must be at least 1");
+        }
+        return new EdtfYear(year, EdtfLevel.L2, significant, false);
+    }
+
+    /**
+     * L2 Y-notation with exponential form, as in {@code Y1E5} (=
+     * {@code 100000}). The value is fully expanded; only the canonical
+     * string form uses the exponential syntax.
+     */
+    public static EdtfYear ofExponential(BigInteger year) {
+        return new EdtfYear(year, EdtfLevel.L2, 0, true);
+    }
+
+    /** L2 Y-notation combining exponential form and significant-digits. */
+    public static EdtfYear ofExponentialSignificant(BigInteger year, int significant) {
+        if (significant < 1) {
+            throw new IllegalArgumentException(
+                "significant-digits count must be at least 1");
+        }
+        return new EdtfYear(year, EdtfLevel.L2, significant, true);
     }
 
     public BigInteger year() { return year; }
 
+    /** 0 when no {@code S} qualifier; otherwise the significant-digits count. */
+    public int significantDigits() { return significantDigits; }
+
+    /** True for L2 Y-notation rendered in exponential form. */
+    public boolean exponential() { return exponential; }
+
     @Override public EdtfType type() { return EdtfType.YEAR; }
 
     @Override public EdtfLevel level() { return level; }
@@ -75,16 +125,49 @@ private void checkInLongRange() {
     }
 
     @Override public String toEdtfString() {
-        // L1 Y-notation always carries the 'Y' prefix so the leading-zero
-        // ambiguity with a four-digit year is resolved.
-        return "Y" + year.toString();
+        StringBuilder sb = new StringBuilder();
+        if (exponential) {
+            sb.append('Y').append(formatExponential(year));
+        } else {
+            sb.append('Y').append(year.toString());
+        }
+        if (significantDigits > 0) {
+            sb.append('S').append(significantDigits);
+        }
+        return sb.toString();
+    }
+
+    /**
+     * Render the value in the {@code coefficient E exponent} form if
+     * lossless, otherwise fall back to plain digits. This matches
+     * edtf.js's canonical output for {@code Y…E…} values by stripping
+     * trailing zeros from the value into the exponent.
+     */
+    private static String formatExponential(BigInteger value) {
+        BigInteger abs = value.abs();
+        if (abs.signum() == 0) return "0E0";
+        String digits = abs.toString();
+        int trailingZeros = 0;
+        while (trailingZeros < digits.length() - 1
+            && digits.charAt(digits.length() - 1 - trailingZeros) == '0') {
+            trailingZeros++;
+        }
+        String coefficient = digits.substring(0, digits.length() - trailingZeros);
+        String sign = value.signum() < 0 ? "-" : "";
+        return sign + coefficient + "E" + trailingZeros;
     }
 
     @Override public String toString() { return toEdtfString(); }
 
     @Override public boolean equals(Object o) {
-        return o instanceof EdtfYear y && y.year.equals(year) && y.level == level;
+        return o instanceof EdtfYear y
+            && y.year.equals(year)
+            && y.level == level
+            && y.significantDigits == significantDigits
+            && y.exponential == exponential;
     }
 
-    @Override public int hashCode() { return Objects.hash(year, level); }
+    @Override public int hashCode() {
+        return Objects.hash(year, level, significantDigits, exponential);
+    }
 }