corvus-numeric-types

name: corvus-numeric-types description: > Understand and work with the Corvus.Text.Json numeric type system including parsed components, BigNumber arbitrary-precision decimal, format-based type selection, and precision-preserving validation. USE FOR: working with JSON numbers in Corvus types, understanding format validation for numeric schemas, implementing numeric operations, choosing between BigNumber and standard .NET numeric types. DO NOT USE FOR: general JSON parsing (use corvus-parsed-documents-and-memory).

Numeric Types

Parsed Component Representation

JSON numbers are stored as raw UTF-8 bytes and parsed on demand into four components:

(isNegative, integral, fractional, exponent)

Example: -123.456e+7 → (true, "123", "456", "+7")

All comparison and validation operates on ASCII digit components — no floating-point conversion. This preserves full precision and avoids IEEE 754 rounding.

BigNumber

An arbitrary-precision decimal: significand × 10^exponent where significand is BigInteger.

// From string
BigNumber bn = BigNumber.Parse("123456789012345678901234567890.123");

// From JSON element
BigNumber bn = element.GetBigNumber();

When to use BigNumber:

• JSON values with > 28 significant digits (beyond decimal precision)
• When exact precision matters (financial, scientific)
• When you need DoS-safe parsing (input capped at 10,000 characters)

Supports all standard .NET format strings: G, F, N, E, C, P, R.

On .NET 9+, BigNumber implements INumber<BigNumber> for full generic math support.

Format-to-Type Mapping

The JSON Schema format keyword maps to .NET types:

Int128, UInt128, and Half have netstandard2.0 fallbacks.

Validation Optimizations

multipleOf Fast Paths

Common divisors have optimized implementations:

• Divisors 1, 2, 3, 4, 5, 6, 8, 10 use specialized integer arithmetic
• Other divisors fall back to BigNumber division

Range Validation

minimum, maximum, exclusiveMinimum, exclusiveMaximum all operate on parsed components (no float conversion), preserving exact precision.

DoS Protection

Numeric input is capped at 10,000 characters (BigNumber.MaxInputLength in src/Corvus.Text.Json/Corvus/Numerics/BigNumber.cs) to prevent resource-exhaustion attacks with extremely large numbers.

Namespaces

Common Pitfalls

• Don't use decimal for arbitrary precision: decimal has 28-29 significant digits max. Use BigNumber for unbounded precision.
• Don't convert to double for comparison: IEEE 754 rounds. Use parsed-component comparison.
• netstandard2.0 limitations: Int128/UInt128/Half aren't available — fallbacks exist but with reduced functionality.

Cross-References

• For parsing JSON documents, see corvus-parsed-documents-and-memory
• For format validation in code generation, see corvus-keywords-and-validation
• Full guide: docs/NumericTypes.md