Fast JSON Double and Float codec (read + write)

[najder-k]

Opt-in faster codec for JSON number serialization/deserialization - JsonOptions(numberCodec = JsonNumberCodec.Fast).

• Write Double/Float: xjb port (XjbDouble/XjbFloat). Always round-trips; char-identical to toString except JDK<19 edge cases (JDK-4511638).
• Read Double/Float: Eisel-Lemire (FastDoubleParser port). Bit-identical to parseDouble/parseFloat.
• BigInt/BigDecimal untouched as of yet (might be in the future).

Benchmarks (to be updated after recent changes)

Measured with JMH, 3 forks × 30 measurement iterations (-f 3 -wi 8 -w 1 -i 10 -r 1), GC
profiler on (-prof gc), on JDK 17.0.18 and JDK 25.0.2, current vs. the released code.
thrpt = throughput in ops/s (higher is better, ± is the 99.9% CI half-width); alloc =
gc.alloc.rate.norm in bytes/op (lower is better). Number payloads: a 128-entry
Map[String, Double], a parse-dominated 512-element List[Double], a mixed 132-key object
(Int/Long/Double/Float), and a List[Long].

Double/Float number codec — the paths this PR changes

JDK 17

Benchmark	Current thrpt	Master thrpt	Δ thrpt	Current alloc	Master alloc	Δ alloc
Double read — Map[String,Double]	35,527 ± 493	27,796 ± 246	+27.8%	40,040	60,352	−33.7%
Double read — List[Double]	23,515 ± 587	12,165 ± 161	+93.3%	71,480	159,217	−55.1%
Double write — Map[String,Double]	80,791 ± 387	48,386 ± 163	+67.0%	13,016	21,480	−39.4%
mixed read (Int/Long/Double/Float)	31,286 ± 665	28,506 ± 898	+9.8%	47,040	61,080	−23.0%
mixed write	110,003 ± 1,888	82,354 ± 1,032	+33.6%	15,816	20,288	−22.0%
List[Long] read	31,171 ± 517	31,268 ± 401	−0.3%	69,840	69,840	0.0%

JDK 25

Benchmark	Current thrpt	Master thrpt	Δ thrpt	Current alloc	Master alloc	Δ alloc
Double read — Map[String,Double]	37,875 ± 589	25,727 ± 518	+47.2%	40,016	58,608	−31.7%
Double read — List[Double]	23,104 ± 137	9,658 ± 111	+139.2%	71,464	151,225	−52.7%
Double write — Map[String,Double]	82,828 ± 808	65,025 ± 362	+27.4%	13,064	25,856	−49.5%
mixed read (Int/Long/Double/Float)	30,596 ± 2,221	25,982 ± 1,014	+17.8%	46,944	58,104	−19.2%
mixed write	118,660 ± 4,134	103,054 ± 1,335	+15.1%	16,968	25,016	−32.2%
List[Long] read	30,627 ± 526	30,695 ± 286	−0.2%	69,840	69,840	0.0%

The write throughput gain is larger on JDK 17 and smaller on JDK 25 because JDK 19+'s Schubfach
already made Double.toString shortest-and-faster; Xjb's own allocation is JDK-independent, so the
write allocation saving is instead larger on JDK 25. Int/Long reads are unchanged from master
and stay at parity with byte-identical allocation.

Tests

2M-value bit-exact sweeps per type; Paxson testbase from A program for Testing IEEE Decimal-Binary Conversion; exhaustive power-of-two sweep; JVM+JS cross test.

Compat

MiMa clean vs 2.21+ (explicit pre-numberCodec apply/copy/ctor overloads). Scala.js supported, tested on Node. Heavy suites JVM-only.

Licensing

xjb (Apache-2.0), FastDoubleParser (MIT) - full notices in headers + THIRD-PARTY-NOTICES.md. Tables generated via BigInteger, not transcribed. No GPL code.

AI disclosure

Developed with Claude Code, Claude Fable 5.

[ddworak]

Does it make sense to keep this separate from the default? Looks like it's fully compatible with the previous format (unless the issues were omitted or not detected).

[najder-k]

Does it make sense to keep this separate from the default? Looks like it's fully compatible with the previous format (unless the issues were omitted or not detected).

I'm open to making it non-configurable, then we should test it more internally before release

[Pituuss]

nit: It is no longer opt in; PR description needs updating

[Pituuss]

class EiselLemireExponentClampTest extends AnyFunSuite {

  private def dbits(d: Double): Long = java.lang.Double.doubleToLongBits(d)
  private def fbits(f: Float): Int = java.lang.Float.floatToIntBits(f)

  // "1" followed by (n-1) zeros, i.e. 10^(n-1), times 10^-19999 -> underflows to 0.0
  private def hugeIntPart(n: Int): String = "1" + ("0" * (n - 1)) + "e-19999"

  test("double: long integer part with a 5-digit negative exponent must match Double.parseDouble") {
    List(1700, 1800, 2300).foreach { digits =>
      val s = hugeIntPart(digits)
      val expected = java.lang.Double.parseDouble(s)
      val actual = EiselLemireDouble.parse(s)
      assert(dbits(actual) == dbits(expected), s"$digits-digit significand: got $actual, expected $expected")
    }
  }

  test("float: long integer part with a 5-digit negative exponent must match Float.parseFloat") {
    List(1997, 2000, 2020).foreach { digits =>
      val s = "9" + ("1" * (digits - 1)) + "e-19999"
      val expected = java.lang.Float.parseFloat(s)
      val actual = EiselLemireFloat.parse(s)
      assert(fbits(actual) == fbits(expected), s"$digits-digit significand: got $actual, expected $expected")
    }
  }

  test("the same input read through JsonStringInput must match the platform parser") {
    val s = hugeIntPart(2300)
    val expected = java.lang.Double.parseDouble(s)
    val actual = JsonStringInput.read[Double](s)
    assert(dbits(actual) == dbits(expected), s"readDouble: got $actual, expected $expected")
  }

  /** Mirror of the same defect in the overflow direction: leading zeros after the dot inflate
    * `truncatedDigitCount`, so a clamped *positive* exponent also lands back in table range. The fast path then
    * returns a finite value where the true value is Infinity — which silently defeats any downstream range check.
    */
  test("double: leading zeros with a clamped positive exponent must not turn Infinity into a finite value") {
    List(925, 1000, 1540).foreach { zeros =>
      val s = "0." + ("0" * zeros) + "1234567890123456789012e12345"
      val expected = java.lang.Double.parseDouble(s)
      val actual = EiselLemireDouble.parse(s)
      assert(dbits(actual) == dbits(expected), s"$zeros leading zeros: got $actual, expected $expected")
    }
  }
}

actually fails, so Read Double/Float: Eisel-Lemire (FastDoubleParser port). Bit-identical to parseDouble/parseFloat. is not correct

sbt:commons> commons-core/testOnly com.avsystem.commons.serialization.json.EiselLemireExponentClampTest
[info] EiselLemireExponentClampTest:
[info] - double: long integer part with a 5-digit negative exponent must match Double.parseDouble *** FAILED ***
[info]   118622047889322841 did not equal 0 1700-digit significand: got 1.0E-300, expected 0.0 (EiselLemireExponentClampTest.scala:29)
[info] - float: long integer part with a 5-digit negative exponent must match Float.parseFloat *** FAILED ***
[info]   1008027333 did not equal 0 1997-digit significand: got 0.009111111, expected 0.0 (EiselLemireExponentClampTest.scala:38)
[info] - the same input read through JsonStringInput must match the platform parser *** FAILED ***
[info]   9094988921128908188 did not equal 0 readDouble: got 1.0E300, expected 0.0 (EiselLemireExponentClampTest.scala:46)
[info] - double: leading zeros with a clamped positive exponent must not turn Infinity into a finite value *** FAILED ***
[info]   9216046942731835485 did not equal 9218868437227405312 925 leading zeros: got 1.2345678901234567E308, expected Infinity (EiselLemireExponentClampTest.scala:58)

[Pituuss]

not included in the jar

[Pituuss]

apache license requires you to include it https://www.apache.org/licenses/LICENSE-2.0.html#redistribution

[Pituuss]

FDP ships with thirdparty-LICENSE so make sure we don't need it