Bodu.Numerics.Serialization.Json Namespace

Package: Bodu.Numerics.Serialization.Json 1.0.0

Bodu.Numerics.Serialization.Json

Purpose

Bodu.Numerics.Serialization.Json carries the System.Text.Json integration for Bodu.Numerics. It supplies the converters that round-trip Fraction<T>, Interval<T>, DiscreteInterval<T>, IntervalSet<T>, BigDecimal, and Complex<T> to and from JSON, together with a one-call extension that registers them under a chosen policy.

The core Bodu.Numerics library is serialization-agnostic - its value types carry no [JsonConverter] attribute and take no dependency on System.Text.Json. Add this package and call AddNumericsJsonConverters to opt into JSON support and select a wire policy across a whole JsonSerializerOptions instance.

Static documentation

Introduction - the converters and factories, the policy model, what is deliberately not covered, and the scenario index.
Core concepts - factories vs closed converters, each type's wire shape, raw-number precision, trimming and AOT, failure modes.
Getting started - install + minimal samples for each policy and each type, including a source-generated context.
Numerics JSON serialization guide - wire formats, the three policies, and registering the converters.

Key types

NumericsJsonSerializerOptionsExtensions - AddNumericsJsonConverters(JsonSerializerOptions, NumericsJsonPolicy) registers the converter factories for every numeric value type on an options instance and returns it for chaining.
NumericsJsonPolicy - the wire-format selector: Strict (default), Lenient, and Compact.
FractionJsonConverter<T>, FractionJsonConverterFactory - converters for Fraction<T>; the factory binds the open-generic converter to the concrete T at run time.
IntervalJsonConverter<T>, IntervalJsonConverterFactory - the equivalent converters for Interval<T>, including the unbounded-endpoint markers.
DiscreteIntervalJsonConverter<T>, IntervalSetJsonConverter<T> (and their factories) - converters for DiscreteInterval<T> (through the interval wire shape) and IntervalSet<T> (a JSON array of pieces).
BigDecimalJsonConverter - the converter for BigDecimal: Strict object shape { "unscaledValue": …, "scale": … } or the compact decimal string. Non-generic, so it registers directly rather than through a factory.
ComplexJsonConverter<T>, ComplexJsonConverterFactory - converters for Complex<T>: Strict object shape { "real": …, "imaginary": … } (non-finite components as the strings "NaN" / "Infinity" / "-Infinity") or the compact "<real; imaginary>" string.
FractionJsonExtensions - the ToJson() / FromJson<T>(string) convenience helpers.

Example

using System.Text.Json;
using Bodu.Numerics;
using Bodu.Numerics.Serialization.Json;

var options = new JsonSerializerOptions()
    .AddNumericsJsonConverters(NumericsJsonPolicy.Strict);

string json = JsonSerializer.Serialize(new Fraction<int>(8, 15), options);
Fraction<int> round = JsonSerializer.Deserialize<Fraction<int>>(json, options);

Notes

Registration is required. The core value types carry no [JsonConverter] attribute, so JSON support is opt-in: call AddNumericsJsonConverters (or add a factory to JsonSerializerOptions.Converters) before serializing.
Factories bind the generic parameter. The generic value types are open generics; the converter factories resolve the concrete T per request, which is why registration adds the factory rather than a closed converter. BigDecimal is the one non-generic type and registers as a single converter.
Pair results are not serializable. IntervalPair<T> and DiscreteIntervalPair<T> are transient operation results; call ToIntervalSet() and serialize the resulting IntervalSet<T>.
See also: the Numerics JSON serialization guide and the Bodu.Numerics overview.

Classes

BigDecimalJsonConverter: Converts a BigDecimal to and from JSON using the policy supplied at construction.

ComplexJsonConverterFactory: Creates ComplexJsonConverter<T> instances for closed Complex<T> types, applying a configurable NumericsJsonPolicy to every closed converter the factory produces.

ComplexJsonConverter<T>: Converts a Complex<T> to and from JSON using the policy supplied at construction.

DiscreteIntervalJsonConverterFactory: Creates DiscreteIntervalJsonConverter<T> instances for closed DiscreteInterval<T> types, applying a configurable NumericsJsonPolicy to every closed converter the factory produces.

DiscreteIntervalJsonConverter<T>: Converts a DiscreteInterval<T> to and from JSON using the policy supplied at construction.

FractionJsonConverterFactory: Creates FractionJsonConverter<T> instances for closed Fraction<T> types, applying a configurable NumericsJsonPolicy to every closed converter the factory produces.

FractionJsonConverter<T>: Converts a Fraction<T> to and from JSON using the policy supplied at construction.

FractionJsonExtensions: Convenience JSON helpers for Fraction<T> that serialize through the Bodu.Numerics converters under a chosen NumericsJsonPolicy.

IntervalJsonConverterFactory: Creates IntervalJsonConverter<T> instances for closed Interval<T> types, applying a configurable NumericsJsonPolicy to every closed converter the factory produces.

IntervalJsonConverter<T>: Converts an Interval<T> to and from JSON using the policy supplied at construction.

IntervalSetJsonConverterFactory: Creates IntervalSetJsonConverter<T> instances for closed IntervalSet<T> types, applying a configurable NumericsJsonPolicy to every closed converter the factory produces.

IntervalSetJsonConverter<T>: Converts an IntervalSet<T> to and from JSON using the policy supplied at construction.

NumericsJsonSerializerOptionsExtensions: Extension methods that register the Bodu.Numerics JSON converters on a JsonSerializerOptions, picking a coherent shape for every shipped numeric type from a single NumericsJsonPolicy value.

Enums

NumericsJsonPolicy: Selects the JSON serialization shape and parsing strictness applied by the Bodu.Numerics JSON converters.

Table of Contents