UnitsNet/UnitsNet.Serialization.JsonNet/QuantityValueFormatOptions.cs at master · angularsen/UnitsNet · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
// Licensed under MIT No Attribution, see LICENSE file at the root.
// Copyright 2013 Andreas Gullberg Larsen (andreas.larsen84@gmail.com). Maintained at https://github.com/angularsen/UnitsNet.

namespace UnitsNet.Serialization.JsonNet;

/// <summary>
///     Represents options for formatting quantity values during serialization and deserialization.
/// </summary>
public record struct QuantityValueFormatOptions(
    QuantityValueSerializationFormat SerializationFormat = QuantityValueSerializationFormat.DecimalPrecision,
    QuantityValueDeserializationFormat DeserializationFormat = QuantityValueDeserializationFormat.ExactNumber);

/// <summary>
///     Specifies the format used for serializing <see cref="QuantityValue" /> to JSON.
/// </summary>
public enum QuantityValueSerializationFormat
{
    /// <summary>
    ///     Represents the serialization format where the quantity value is serialized as a number with decimal precision.
    /// </summary>
    /// <remarks>
    ///     This number is represented with up to 29 significant digits. Numbers such as "1/3" would be represented as
    ///     "0.3333333333333333333333333333".
    /// </remarks>
    DecimalPrecision,

    /// <summary>
    ///     Represents the serialization format where the quantity value is serialized as a number with double precision.
    /// </summary>
    /// <remarks>
    ///     This number is represented with up to 17 significant digits. Numbers such as "1/3" would be represented as
    ///     "0.3333333333333333".
    /// </remarks>
    DoublePrecision,

    /// <summary>
    ///     Represents a serialization format that ensures the exact value of a quantity is preserved during serialization and
    ///     deserialization.
    ///     This format is particularly useful for scenarios where precision and round-trip accuracy are critical.
    /// </summary>
    /// <remarks>
    ///     This format dynamically switches between decimal and fractional notation
    ///     depending on the value being serialized. This ensures that the serialized representation is both precise and
    ///     compact.
    ///     For example:
    ///     - A value such as <c>1.23456789</c> will be serialized in decimal notation, including all significant digits.
    ///     - A value such as <c>1/3</c> will be serialized as a fraction (e.g., <c>"1/3"</c>).
    ///     This format is ideal for scenarios where the exact representation of a value is required for round-trip
    ///     serialization and deserialization.
    /// </remarks>
    RoundTrip,

    /// <summary>
    ///     Relies on the presence of a custom converter for the <see cref="QuantityValue" />.
    /// </summary>
    /// <remarks>
    ///     When this option is selected <c>JsonConvert</c> is used for the serialization.
    /// </remarks>
    Custom
}

/// <summary>
///     Specifies the format used for deserializing <see cref="QuantityValue" /> from JSON.
/// </summary>
public enum QuantityValueDeserializationFormat
{
    /// <summary>
    ///     Deserializes the numeric value of a JSON number exactly, without converting through <see cref="double" /> or
    ///     <see cref="decimal" />.
    /// </summary>
    /// <remarks>
    ///     Every digit is parsed directly into a <see cref="QuantityValue" />. The original textual representation is not
    ///     retained, so equivalent JSON numbers such as <c>1.2300e2</c> and <c>123</c> produce the same numeric value.
    /// </remarks>
    ExactNumber,

    /// <summary>
    ///     Deserializes the quantity value as a double precision number, which is then rounded to 15 significant digits.
    /// </summary>
    RoundedDouble,

    /// <summary>
    ///     Represents a serialization format that ensures the exact value of a quantity is preserved during serialization and
    ///     deserialization.
    ///     This format is particularly useful for scenarios where precision and round-trip accuracy are critical.
    /// </summary>
    /// <remarks>
    ///     This format dynamically switches between decimal and fractional notation
    ///     depending on the value being serialized. This ensures that the serialized representation is both precise and
    ///     compact.
    ///     For example:
    ///     - A value such as <c>1.23456789</c> will be serialized in decimal notation, including all significant digits.
    ///     - A value such as <c>1/3</c> will be serialized as a fraction (e.g., <c>"1/3"</c>).
    ///     This format is ideal for scenarios where the exact representation of a value is required for round-trip
    ///     serialization and deserialization.
    /// </remarks>
    RoundTrip,

    /// <summary>
    ///     Relies on the presence of a custom converter for the <see cref="QuantityValue" />.
    /// </summary>
    /// <remarks>
    ///     When this option is selected <c>JsonConvert</c> is used for the deserialization.
    /// </remarks>
    Custom
}