Skip to main content

nautilus_core/serialization/
decimal.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Exact decimal parsing and JSON serialization contracts.
17//!
18//! Exact decimal ingestion, separate from instrument and currency rounding.
19//!
20//! [`deserialize_json`] preserves quoted and unquoted JSON tokens with the default features.
21//! It uses `RawValue`, which Serde's internally tagged and untagged enum buffers do not support.
22//!
23//! Use [`deserialize`] for those buffers: strings and 64-bit integers work with all feature sets.
24//! Larger integers, fractional tokens, and scientific numeric tokens require
25//! `serde_json/arbitrary_precision` from the first JSON parse. Floats are rejected because their
26//! original decimal digits are unavailable.
27//! Even with arbitrary precision, `Number`'s Serde deserializer delivers some decimals as floats.
28//! For buffered `Value` use [`deserialize_json`]; for `Number` use `parse(&number.to_string())`.
29//! These routes preserve the buffered decimal text when arbitrary precision was enabled at ingest.
30//! Serde enum buffering of a `Value` may still deliver floats, which are rejected.
31//!
32//! The visitor also accepts `serde_json`'s private number-map encoding with arbitrary precision enabled.
33//! A literal JSON object using that reserved key is indistinguishable from the numeric encoding.
34//! Use the raw-token route before buffering when every JSON object must be rejected.
35//! With arbitrary precision, `Value` parsing itself interprets the reserved object as a number.
36//!
37//! A `Value` or `Number` created through floating-point conversion has already lost its source
38//! spelling. No API here recovers those digits. In particular, passing a default-feature `Value`
39//! to [`deserialize_json`] reparses its rendered value, not the original JSON token.
40//!
41//! Required fields reject missing, null, empty, invalid, overflowing, and underflowing values.
42//! Optional fields accept null as `None`; add `#[serde(default)]` to accept missing fields.
43//! Empty strings remain errors. Representability concerns numeric value, so redundant trailing
44//! zeros may be removed. Instrument precision and currency rounding belong to model constructors.
45//!
46//! [`serialize`] emits exact JSON numbers, including through `serde_json::to_value`. Enable
47//! `serde_json/arbitrary_precision` for the full Decimal range. Without it, values whose numeric
48//! value would change are errors. String output uses
49//! [`serialize_decimal_as_str`](crate::serialization::serialize_decimal_as_str) and
50//! [`serialize_optional_decimal_as_str`](crate::serialization::serialize_optional_decimal_as_str).
51//! These JSON number contracts do not extend to MessagePack or other Serde formats.
52//! The parent module's permissive deserializers accept null and empty strings, round excess
53//! fractional digits, and preserve exactly representable scientific strings.
54//! Oversized integer inputs return errors.
55
56use std::str::FromStr;
57
58use rust_decimal::Decimal;
59use serde::{
60    Deserialize, Deserializer, Serialize, Serializer,
61    de::{Error, MapAccess, Visitor, value::MapAccessDeserializer},
62};
63use serde_json::{Number, value::RawValue};
64
65use super::{DecimalVisitor, decimal_components, json_token_text};
66
67/// Deserializes an exact decimal from strings, integers, or arbitrary-precision number maps.
68///
69/// Supports direct JSON and Serde enum buffers. Integers outside the 64-bit range, fractional
70/// tokens, and scientific numeric tokens require `serde_json/arbitrary_precision`.
71/// Use [`deserialize_json`] for default-feature JSON or buffered
72/// `Value`. Some buffered `Number` values use Serde's float route even with arbitrary precision;
73/// parse their text with [`parse`] instead.
74/// With arbitrary precision, accepts `serde_json`'s private number maps, including literal objects
75/// with the same reserved key.
76/// Use [`deserialize_json`] before buffering when the original JSON shape must be checked.
77///
78/// # Errors
79///
80/// Returns an error if:
81/// - The input is a float, null, an empty string, or an invalid decimal.
82/// - Representing the value requires rounding.
83pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Decimal, D::Error> {
84    deserializer.deserialize_any(ExactDecimalVisitor)
85}
86
87/// Deserializes an optional exact decimal, accepting null as `None`.
88///
89/// Add `#[serde(default)]` to accept a missing field. Other values follow [`deserialize`].
90///
91/// # Errors
92///
93/// Returns an error if [`deserialize`] rejects a non-null value.
94pub fn deserialize_optional<'de, D: Deserializer<'de>>(
95    deserializer: D,
96) -> Result<Option<Decimal>, D::Error> {
97    deserializer.deserialize_option(OptionalExactDecimalVisitor)
98}
99
100/// Deserializes an exact decimal directly from a quoted or unquoted JSON token.
101///
102/// Works without arbitrary precision. Use before `Value` buffering to preserve source digits.
103/// Serde internally tagged and untagged enum buffers do not support this raw-token route.
104///
105/// # Errors
106///
107/// Returns an error if:
108/// - The input is null, an empty string, a non-decimal shape, or an invalid decimal.
109/// - Representing the value requires rounding.
110pub fn deserialize_json<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Decimal, D::Error> {
111    let raw = Box::<RawValue>::deserialize(deserializer)?;
112    parse_json(&raw).map_err(D::Error::custom)
113}
114
115/// Deserializes an optional exact JSON decimal, accepting null as `None`.
116///
117/// Add `#[serde(default)]` to accept a missing field. Other values follow [`deserialize_json`].
118///
119/// # Errors
120///
121/// Returns an error if [`deserialize_json`] rejects a non-null value.
122pub fn deserialize_optional_json<'de, D: Deserializer<'de>>(
123    deserializer: D,
124) -> Result<Option<Decimal>, D::Error> {
125    Option::<Box<RawValue>>::deserialize(deserializer)?
126        .map(|raw| parse_json(&raw).map_err(D::Error::custom))
127        .transpose()
128}
129
130/// Serializes a decimal as a JSON number without changing its numeric value.
131///
132/// Checks the `Number` representation before serialization so `to_value` is also lossless.
133/// The full Decimal range requires `serde_json/arbitrary_precision`. Without that feature,
134/// scale is not preserved and output may use exponent notation. Check the receiving API's
135/// numeric syntax before using this serializer for wire payloads.
136///
137/// Raw-token serializers can emit the full Decimal range directly to JSON text without arbitrary
138/// precision. Replacing them with this serializer can reject previously supported values unless
139/// `serde_json/arbitrary_precision` is enabled. Use [`super::serialize_decimal_as_str`] for
140/// portable string output.
141///
142/// # Errors
143///
144/// Returns an error if:
145/// - The enabled JSON representation would round the value.
146/// - Serialization fails.
147pub fn serialize<S: Serializer>(value: &Decimal, serializer: S) -> Result<S::Ok, S::Error> {
148    let number = Number::from_str(&value.to_string()).map_err(serde::ser::Error::custom)?;
149    let represented = parse(&number.to_string()).map_err(serde::ser::Error::custom)?;
150    if represented != *value {
151        return Err(serde::ser::Error::custom(
152            "exact decimal number serialization requires serde_json/arbitrary_precision",
153        ));
154    }
155
156    number.serialize(serializer)
157}
158
159/// Serializes an optional decimal as an exact JSON number or null.
160///
161/// # Errors
162///
163/// Returns an error if [`serialize`] fails, or if serializing null fails.
164pub fn serialize_optional<S: Serializer>(
165    value: &Option<Decimal>,
166    serializer: S,
167) -> Result<S::Ok, S::Error> {
168    match value {
169        Some(value) => serialize(value, serializer),
170        None => serializer.serialize_none(),
171    }
172}
173
174/// Parses a decimal or scientific string without rounding its numeric value.
175///
176/// Accepts signs, decimal points, and digit separators supported by `rust_decimal`.
177/// Scientific input is normalized. Plain input drops redundant trailing zeros only when needed
178/// to fit Decimal's mantissa or scale.
179/// Scientific exponents must fit `i64`.
180///
181/// # Errors
182///
183/// Returns an error if:
184/// - The input is not a valid decimal or scientific string.
185/// - The value exceeds Decimal's exact mantissa or scale bounds.
186pub fn parse(value: &str) -> Result<Decimal, rust_decimal::Error> {
187    // `from_str_exact` rejects exponent markers, so plain input needs no scan for them first
188    if let Ok(value) = Decimal::from_str_exact(value) {
189        return Ok(value);
190    }
191
192    // Normalize the significand before construction: from_scientific parses its base with
193    // the rounding FromStr implementation, even when the final value is representable.
194    let (base, exponent) = match value.split_once(['e', 'E']) {
195        Some((base, exponent)) => (
196            base,
197            exponent
198                .parse::<i64>()
199                .map_err(|_| rust_decimal::Error::from("invalid decimal exponent"))?,
200        ),
201        None => (value, 0),
202    };
203
204    let negative = base.starts_with('-');
205    let base = base.strip_prefix(['-', '+']).unwrap_or(base);
206    if base.starts_with('_') || base.starts_with("._") {
207        return Err(rust_decimal::Error::from("invalid decimal significand"));
208    }
209
210    let base = base.replace('_', "");
211    let (whole, fraction) = decimal_components(&base)
212        .ok_or_else(|| rust_decimal::Error::from("invalid decimal significand"))?;
213    let mut digits = format!("{whole}{fraction}");
214    let mut scale = i64::try_from(fraction.len())
215        .ok()
216        .and_then(|scale| scale.checked_sub(exponent))
217        .ok_or_else(|| rust_decimal::Error::from("decimal scale out of range"))?;
218    digits = digits.trim_start_matches('0').to_string();
219    if digits.is_empty() {
220        return Ok(Decimal::ZERO);
221    }
222
223    while scale > 0 && digits.ends_with('0') {
224        digits.pop();
225        scale -= 1;
226    }
227
228    if scale < 0 {
229        let zeros = scale
230            .checked_neg()
231            .and_then(|scale| usize::try_from(scale).ok())
232            .filter(|zeros| digits.len().saturating_add(*zeros) <= 29)
233            .ok_or(rust_decimal::Error::ExceedsMaximumPossibleValue)?;
234        digits.extend(std::iter::repeat_n('0', zeros));
235        scale = 0;
236    }
237
238    let scale = u32::try_from(scale).map_err(|_| rust_decimal::Error::Underflow)?;
239    if scale > Decimal::MAX_SCALE {
240        return Err(rust_decimal::Error::Underflow);
241    }
242
243    let mantissa = digits
244        .parse::<i128>()
245        .map_err(|_| rust_decimal::Error::ExceedsMaximumPossibleValue)?;
246    Decimal::try_from_i128_with_scale(if negative { -mantissa } else { mantissa }, scale)
247}
248
249fn parse_json(raw: &RawValue) -> Result<Decimal, String> {
250    let text = json_token_text(raw).map_err(|e| e.to_string())?;
251    parse(&text).map_err(|e| e.to_string())
252}
253
254struct ExactDecimalVisitor;
255
256impl<'de> Visitor<'de> for ExactDecimalVisitor {
257    type Value = Decimal;
258
259    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
260        formatter
261            .write_str("an exact decimal string or integer, or an arbitrary-precision JSON number")
262    }
263
264    fn visit_str<E: Error>(self, value: &str) -> Result<Self::Value, E> {
265        parse(value).map_err(E::custom)
266    }
267
268    fn visit_i64<E: Error>(self, value: i64) -> Result<Self::Value, E> {
269        DecimalVisitor.visit_i64(value)
270    }
271
272    fn visit_u64<E: Error>(self, value: u64) -> Result<Self::Value, E> {
273        DecimalVisitor.visit_u64(value)
274    }
275
276    fn visit_i128<E: Error>(self, value: i128) -> Result<Self::Value, E> {
277        DecimalVisitor.visit_i128(value)
278    }
279
280    fn visit_u128<E: Error>(self, value: u128) -> Result<Self::Value, E> {
281        DecimalVisitor.visit_u128(value)
282    }
283
284    fn visit_map<A: MapAccess<'de>>(self, map: A) -> Result<Self::Value, A::Error> {
285        let number = Number::deserialize(MapAccessDeserializer::new(map))?;
286        parse(&number.to_string()).map_err(A::Error::custom)
287    }
288}
289
290struct OptionalExactDecimalVisitor;
291
292impl<'de> Visitor<'de> for OptionalExactDecimalVisitor {
293    type Value = Option<Decimal>;
294
295    fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
296        formatter.write_str("null or an exact decimal")
297    }
298
299    fn visit_none<E: Error>(self) -> Result<Self::Value, E> {
300        Ok(None)
301    }
302
303    fn visit_unit<E: Error>(self) -> Result<Self::Value, E> {
304        Ok(None)
305    }
306
307    fn visit_some<D: Deserializer<'de>>(self, deserializer: D) -> Result<Self::Value, D::Error> {
308        deserialize(deserializer).map(Some)
309    }
310}
311
312#[cfg(test)]
313mod tests {
314    use std::{collections::BTreeMap, str::FromStr};
315
316    use proptest::prelude::*;
317    use rstest::rstest;
318    use rust_decimal::Decimal;
319    use rust_decimal_macros::dec;
320    use serde::{
321        Deserialize, Serialize,
322        de::value::{Error, F64Deserializer, I128Deserializer, U128Deserializer},
323    };
324    use serde_json::{Number, Value, value::RawValue};
325
326    use crate::serialization::{self, decimal};
327
328    #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
329    struct Exact(#[serde(with = "decimal")] Decimal);
330
331    #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
332    struct Raw(
333        #[serde(
334            deserialize_with = "decimal::deserialize_json",
335            serialize_with = "decimal::serialize"
336        )]
337        Decimal,
338    );
339
340    #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
341    struct Optional {
342        #[serde(
343            default,
344            deserialize_with = "decimal::deserialize_optional",
345            serialize_with = "decimal::serialize_optional"
346        )]
347        value: Option<Decimal>,
348    }
349
350    #[derive(Debug, PartialEq, Eq, Deserialize)]
351    struct OptionalRaw {
352        #[serde(default, deserialize_with = "decimal::deserialize_optional_json")]
353        value: Option<Decimal>,
354    }
355
356    #[derive(Debug, Deserialize)]
357    struct Required {
358        #[serde(deserialize_with = "decimal::deserialize")]
359        value: Decimal,
360    }
361
362    #[derive(Debug, Deserialize)]
363    struct RequiredRaw {
364        #[serde(deserialize_with = "decimal::deserialize_json")]
365        value: Decimal,
366    }
367
368    #[derive(Debug, PartialEq, Eq, Deserialize)]
369    #[serde(tag = "kind")]
370    enum Tagged {
371        Amount {
372            #[serde(deserialize_with = "decimal::deserialize")]
373            value: Decimal,
374        },
375    }
376
377    #[derive(Debug, PartialEq, Eq, Deserialize)]
378    #[serde(untagged)]
379    enum Untagged {
380        Amount {
381            #[serde(deserialize_with = "decimal::deserialize")]
382            value: Decimal,
383        },
384    }
385
386    #[derive(Debug, Deserialize)]
387    #[serde(tag = "kind")]
388    enum TaggedRaw {
389        Amount {
390            #[serde(rename = "value", deserialize_with = "decimal::deserialize_json")]
391            _value: Decimal,
392        },
393    }
394
395    #[derive(Debug, Deserialize)]
396    #[serde(untagged)]
397    enum UntaggedRaw {
398        Amount {
399            #[serde(rename = "value", deserialize_with = "decimal::deserialize_json")]
400            _value: Decimal,
401        },
402    }
403
404    fn cases() -> [(&'static str, Decimal, bool); 22] {
405        // Probe dependency behavior because Cargo unifies serde_json features across crates
406        let float_roundtrip =
407            serde_json::from_str::<f64>("1e-28").unwrap().to_bits() == 1e-28_f64.to_bits();
408
409        [
410            ("123456789.123456789", dec!(123456789.123456789), false),
411            ("0.12345678901234568", dec!(0.12345678901234568), true),
412            ("9007199254740993", dec!(9007199254740993), true),
413            ("18446744073709551617", dec!(18446744073709551617), false),
414            (
415                "79228162514264337593543950335",
416                dec!(79228162514264337593543950335),
417                false,
418            ),
419            (
420                "-79228162514264337593543950335",
421                dec!(-79228162514264337593543950335),
422                false,
423            ),
424            (
425                "1e-28",
426                dec!(0.0000000000000000000000000001),
427                float_roundtrip,
428            ),
429            (
430                "10e-29",
431                dec!(0.0000000000000000000000000001),
432                float_roundtrip,
433            ),
434            ("1e28", dec!(10000000000000000000000000000), true),
435            ("0.1e29", dec!(10000000000000000000000000000), true),
436            (
437                "792281625142643375935439503350e-1",
438                dec!(79228162514264337593543950335),
439                false,
440            ),
441            (
442                "7.9228162514264337593543950335e28",
443                dec!(79228162514264337593543950335),
444                false,
445            ),
446            (
447                "0.00000000000000000000000000010",
448                dec!(0.0000000000000000000000000001),
449                float_roundtrip,
450            ),
451            (
452                "79228162514264337593543950335.0",
453                dec!(79228162514264337593543950335),
454                false,
455            ),
456            (
457                "1.234567890123456789012345678900E+1",
458                dec!(12.345678901234567890123456789),
459                false,
460            ),
461            ("-0.0", dec!(0), true),
462            ("0e1000000", dec!(0), true),
463            ("-3.75E+2", dec!(-375), true),
464            ("-375", dec!(-375), true),
465            (
466                "0.00000000000000000000000000001e1",
467                dec!(0.0000000000000000000000000001),
468                float_roundtrip,
469            ),
470            ("-12345e-4", dec!(-1.2345), true),
471            (
472                "1.234567890123456789012345678e-1",
473                dec!(0.1234567890123456789012345678),
474                false,
475            ),
476        ]
477    }
478
479    fn arbitrary_precision() -> bool {
480        Number::from_str(&Decimal::MAX.to_string())
481            .unwrap()
482            .to_string()
483            == Decimal::MAX.to_string()
484    }
485
486    fn object(token: &str, tagged: bool) -> String {
487        let mut fields = BTreeMap::new();
488        fields.insert("value", RawValue::from_string(token.to_string()).unwrap());
489
490        if tagged {
491            fields.insert(
492                "kind",
493                RawValue::from_string(serde_json::to_string("Amount").unwrap()).unwrap(),
494            );
495        }
496
497        serde_json::to_string(&fields).unwrap()
498    }
499
500    #[rstest]
501    fn exact_quoted_and_numeric_tokens() {
502        for (token, expected, _) in cases() {
503            let quoted = serde_json::to_string(&token).unwrap();
504            assert_eq!(decimal::parse(token).unwrap(), expected, "{token}");
505            assert_eq!(serde_json::from_str::<Raw>(token).unwrap(), Raw(expected));
506            assert_eq!(
507                serde_json::from_slice::<Raw>(token.as_bytes()).unwrap(),
508                Raw(expected)
509            );
510            assert_eq!(
511                serde_json::from_reader::<_, Raw>(token.as_bytes()).unwrap(),
512                Raw(expected)
513            );
514            assert_eq!(serde_json::from_str::<Raw>(&quoted).unwrap(), Raw(expected));
515            assert_eq!(
516                serde_json::from_str::<Exact>(&quoted).unwrap(),
517                Exact(expected)
518            );
519            let number: Number = serde_json::from_str(token).unwrap();
520            let direct = serde_json::from_str::<Exact>(token);
521            let buffered = serde_json::from_value::<Exact>(Value::Number(number.clone()));
522            let from_number = decimal::deserialize(number.clone());
523            if arbitrary_precision() || number.is_i64() || number.is_u64() {
524                assert_eq!(direct.unwrap(), Exact(expected));
525                assert_eq!(
526                    serde_json::from_value::<Raw>(Value::Number(number.clone())).unwrap(),
527                    Raw(expected)
528                );
529                assert_eq!(decimal::parse(&number.to_string()).unwrap(), expected);
530
531                match (buffered, from_number) {
532                    (Ok(buffered), Ok(from_number)) => {
533                        assert_eq!(buffered, Exact(expected));
534                        assert_eq!(from_number, expected);
535                    }
536                    (Err(buffered), Err(from_number)) => {
537                        assert!(buffered.to_string().contains("floating point"));
538                        assert!(from_number.to_string().contains("floating point"));
539                    }
540                    results => panic!("buffered routes disagree: {results:?}"),
541                }
542            } else {
543                assert!(direct.is_err(), "{token}");
544                assert!(buffered.is_err(), "{token}");
545                assert!(from_number.is_err(), "{token}");
546            }
547        }
548    }
549
550    #[rstest]
551    fn invalid_values_and_shapes() {
552        for token in [
553            "79228162514264337593543950336",
554            "-79228162514264337593543950336",
555            "1e29",
556            "1e-29",
557            "-1e-29",
558            "0.00000000000000000000000000001",
559            "1.00000000000000000000000000001",
560            "79228162514264337593543950335.1",
561            "1e9223372036854775807",
562            "1e-9223372036854775808",
563            "1e9223372036854775808",
564            "1.2.3e1",
565            "",
566            "NaN",
567            "Infinity",
568            "1e",
569            "1e1e1",
570            "--1",
571            "0.12345678901234567890123456789e0",
572            "0.12345678901234567890123456789",
573            "--1e0",
574            "_1",
575            "._1",
576            "_1e1",
577            "._1e1",
578        ] {
579            assert!(decimal::parse(token).is_err(), "{token}");
580            let quoted = serde_json::to_string(&token).unwrap();
581            assert!(serde_json::from_str::<Raw>(&quoted).is_err(), "{token}");
582            assert!(serde_json::from_str::<Exact>(&quoted).is_err(), "{token}");
583            assert!(serde_json::from_str::<Raw>(token).is_err(), "{token}");
584            assert!(serde_json::from_str::<Exact>(token).is_err(), "{token}");
585            let json = object(&quoted, false);
586            assert!(serde_json::from_str::<Optional>(&json).is_err(), "{token}");
587            assert!(
588                serde_json::from_str::<OptionalRaw>(&json).is_err(),
589                "{token}"
590            );
591
592            if let Ok(value) = serde_json::from_str::<Value>(token) {
593                assert!(
594                    serde_json::from_value::<Exact>(value.clone()).is_err(),
595                    "{token}"
596                );
597
598                if arbitrary_precision() {
599                    assert!(serde_json::from_value::<Raw>(value).is_err(), "{token}");
600                }
601            }
602        }
603
604        for token in ["null", "true", "false", "[]", "{}", "{\"amount\":1}"] {
605            assert!(serde_json::from_str::<Raw>(token).is_err(), "{token}");
606            assert!(serde_json::from_str::<Exact>(token).is_err(), "{token}");
607        }
608    }
609
610    #[rstest]
611    #[case("+1_234.50E-2", dec!(12.345))]
612    #[case("1.2_5", dec!(1.25))]
613    #[case(".5e1", dec!(5))]
614    fn quoted_decimal_syntax(#[case] token: &str, #[case] expected: Decimal) {
615        let json = serde_json::to_string(token).unwrap();
616        assert_eq!(decimal::parse(token).unwrap(), expected);
617        assert_eq!(serde_json::from_str::<Raw>(&json).unwrap(), Raw(expected));
618        assert_eq!(
619            serde_json::from_str::<Exact>(&json).unwrap(),
620            Exact(expected)
621        );
622    }
623
624    #[rstest]
625    fn quoted_json_escapes() {
626        assert_eq!(
627            serde_json::from_str::<Raw>(r#""\u0031.25""#).unwrap(),
628            Raw(dec!(1.25))
629        );
630        assert!(serde_json::from_str::<Raw>(r#""\uD800""#).is_err());
631    }
632
633    #[rstest]
634    fn private_number_map_requires_raw_shape_validation() {
635        let private_number = r#"{"$serde_json::private::Number":"123456789.123456789"}"#;
636        assert!(serde_json::from_str::<Raw>(private_number).is_err());
637        let direct = serde_json::from_str::<Exact>(private_number);
638        let value: Value = serde_json::from_str(private_number).unwrap();
639
640        if arbitrary_precision() {
641            assert_eq!(direct.unwrap(), Exact(dec!(123456789.123456789)));
642            assert!(value.is_number());
643            assert_eq!(
644                serde_json::from_value::<Raw>(value).unwrap(),
645                Raw(dec!(123456789.123456789))
646            );
647        } else {
648            assert!(direct.is_err());
649            assert!(value.is_object());
650            assert!(serde_json::from_value::<Raw>(value).is_err());
651        }
652
653        for token in [
654            "{\"$serde_json::private::Number\":\"not-a-number\"}",
655            "{\"$serde_json::private::Number\":\"1e-29\"}",
656            "{\"$serde_json::private::Number\":\"79228162514264337593543950336\"}",
657        ] {
658            assert!(serde_json::from_str::<Raw>(token).is_err());
659            assert!(serde_json::from_str::<Exact>(token).is_err());
660        }
661    }
662
663    #[rstest]
664    fn presence_semantics() {
665        for json in ["{}", r#"{"value":null}"#] {
666            assert!(serde_json::from_str::<Required>(json).is_err());
667            assert!(serde_json::from_str::<RequiredRaw>(json).is_err());
668            assert_eq!(
669                serde_json::from_str::<Optional>(json).unwrap(),
670                Optional { value: None }
671            );
672            assert_eq!(
673                serde_json::from_str::<OptionalRaw>(json).unwrap(),
674                OptionalRaw { value: None }
675            );
676        }
677
678        let empty = r#"{"value":""}"#;
679        assert!(serde_json::from_str::<Required>(empty).is_err());
680        assert!(serde_json::from_str::<RequiredRaw>(empty).is_err());
681        assert!(serde_json::from_str::<Optional>(empty).is_err());
682        assert!(serde_json::from_str::<OptionalRaw>(empty).is_err());
683
684        for (token, expected, _) in cases() {
685            let json = object(&serde_json::to_string(&token).unwrap(), false);
686            assert_eq!(
687                serde_json::from_str::<Required>(&json).unwrap().value,
688                expected
689            );
690            assert_eq!(
691                serde_json::from_str::<RequiredRaw>(&json).unwrap().value,
692                expected
693            );
694            assert_eq!(
695                serde_json::from_str::<Optional>(&json).unwrap().value,
696                Some(expected)
697            );
698            assert_eq!(
699                serde_json::from_str::<OptionalRaw>(&json).unwrap().value,
700                Some(expected)
701            );
702            let numeric = object(token, false);
703            assert_eq!(
704                serde_json::from_str::<OptionalRaw>(&numeric).unwrap().value,
705                Some(expected)
706            );
707            let optional = serde_json::from_str::<Optional>(&numeric);
708            let number = Number::from_str(token).unwrap();
709            if arbitrary_precision() || number.is_i64() || number.is_u64() {
710                assert_eq!(optional.unwrap().value, Some(expected));
711            } else {
712                assert!(optional.is_err());
713            }
714        }
715    }
716
717    #[rstest]
718    fn serde_enum_buffering() {
719        for (token, expected, _) in cases() {
720            let quoted = serde_json::to_string(&token).unwrap();
721            let tagged = object(&quoted, true);
722            let untagged = object(&quoted, false);
723            assert_eq!(
724                serde_json::from_str::<Tagged>(&tagged).unwrap(),
725                Tagged::Amount { value: expected }
726            );
727            assert_eq!(
728                serde_json::from_str::<Untagged>(&untagged).unwrap(),
729                Untagged::Amount { value: expected }
730            );
731            assert!(serde_json::from_str::<TaggedRaw>(&tagged).is_err());
732            assert!(serde_json::from_str::<UntaggedRaw>(&untagged).is_err());
733            let tagged = serde_json::from_str::<Tagged>(&object(token, true));
734            let untagged = serde_json::from_str::<Untagged>(&object(token, false));
735            let number = Number::from_str(token).unwrap();
736            if arbitrary_precision() || number.is_i64() || number.is_u64() {
737                assert_eq!(tagged.unwrap(), Tagged::Amount { value: expected });
738                assert_eq!(untagged.unwrap(), Untagged::Amount { value: expected });
739            } else {
740                assert!(tagged.is_err());
741                assert!(untagged.is_err());
742            }
743        }
744    }
745
746    #[rstest]
747    #[case(Decimal::MAX.mantissa(), Some(Decimal::MAX))]
748    #[case(Decimal::MIN.mantissa(), Some(Decimal::MIN))]
749    #[case(Decimal::MAX.mantissa() + 1, None)]
750    #[case(Decimal::MIN.mantissa() - 1, None)]
751    #[case(i128::MAX, None)]
752    #[case(i128::MIN, None)]
753    fn signed_integer_bounds(#[case] value: i128, #[case] expected: Option<Decimal>) {
754        assert_eq!(
755            decimal::deserialize(I128Deserializer::<Error>::new(value)).ok(),
756            expected
757        );
758        assert_eq!(
759            serialization::deserialize_decimal(I128Deserializer::<Error>::new(value)).ok(),
760            expected
761        );
762        assert_eq!(
763            serialization::deserialize_optional_decimal(I128Deserializer::<Error>::new(value)).ok(),
764            expected.map(Some)
765        );
766    }
767
768    #[rstest]
769    #[case(9_007_199_254_740_993, Some(dec!(9007199254740993)))]
770    #[case(18_446_744_073_709_551_617, Some(dec!(18446744073709551617)))]
771    #[case(Decimal::MAX.mantissa().unsigned_abs(), Some(Decimal::MAX))]
772    #[case(Decimal::MAX.mantissa().unsigned_abs() + 1, None)]
773    #[case(u128::MAX, None)]
774    fn unsigned_integer_bounds(#[case] value: u128, #[case] expected: Option<Decimal>) {
775        assert_eq!(
776            decimal::deserialize(U128Deserializer::<Error>::new(value)).ok(),
777            expected
778        );
779        assert_eq!(
780            serialization::deserialize_decimal(U128Deserializer::<Error>::new(value)).ok(),
781            expected
782        );
783        assert_eq!(
784            serialization::deserialize_optional_decimal(U128Deserializer::<Error>::new(value)).ok(),
785            expected.map(Some)
786        );
787    }
788
789    #[rstest]
790    #[case(0.5)]
791    #[case(f64::NAN)]
792    #[case(f64::INFINITY)]
793    fn buffered_floats_are_rejected(#[case] value: f64) {
794        assert!(decimal::deserialize(F64Deserializer::<Error>::new(value)).is_err());
795    }
796
797    #[rstest]
798    fn exact_numeric_serialization() {
799        for (token, expected, default_numeric) in cases() {
800            let text = serde_json::to_string(&Exact(expected));
801            let value = serde_json::to_value(Exact(expected));
802
803            let optional = serde_json::to_value(Optional {
804                value: Some(expected),
805            });
806
807            let supported = arbitrary_precision() || default_numeric;
808            assert_eq!(text.is_ok(), supported, "{token}: {text:?}");
809            assert_eq!(value.is_ok(), supported);
810            assert_eq!(optional.is_ok(), supported);
811
812            if supported {
813                let value = value.unwrap();
814                assert!(value.is_number());
815                assert_eq!(
816                    serde_json::from_str::<Raw>(&text.unwrap()).unwrap(),
817                    Raw(expected)
818                );
819                assert_eq!(
820                    serde_json::from_value::<Raw>(value.clone()).unwrap(),
821                    Raw(expected)
822                );
823                assert_eq!(decimal::parse(&value.to_string()).unwrap(), expected);
824                assert_eq!(optional.unwrap()["value"], value);
825            }
826        }
827
828        assert_eq!(
829            serde_json::to_value(Optional { value: None }).unwrap(),
830            serde_json::json!({"value": null})
831        );
832    }
833
834    #[rstest]
835    fn buffered_precision_boundary() {
836        let token = "0.12345678901234568";
837        let number = Number::from_str(token).unwrap();
838        let value = Value::Number(number.clone());
839        assert!(
840            decimal::deserialize(number.clone())
841                .unwrap_err()
842                .to_string()
843                .contains("floating point")
844        );
845        assert!(
846            serde_json::from_value::<Exact>(value.clone())
847                .unwrap_err()
848                .to_string()
849                .contains("floating point")
850        );
851        assert_eq!(
852            decimal::parse(&number.to_string()).unwrap(),
853            dec!(0.12345678901234568)
854        );
855        assert_eq!(
856            serde_json::from_value::<Raw>(value).unwrap(),
857            Raw(dec!(0.12345678901234568))
858        );
859
860        let original = "123456789.123456789";
861        let value: Value = serde_json::from_str(original).unwrap();
862        let buffered = serde_json::from_value::<Raw>(value).unwrap();
863
864        let expected = if arbitrary_precision() {
865            dec!(123456789.123456789)
866        } else {
867            dec!(123456789.12345679)
868        };
869
870        assert_eq!(buffered, Raw(expected));
871        assert_eq!(
872            serde_json::from_str::<Raw>(original).unwrap(),
873            Raw(dec!(123456789.123456789))
874        );
875    }
876
877    #[rstest]
878    fn permissive_buffered_overflow_returns_error() {
879        for token in [
880            "79228162514264337593543950336",
881            "-79228162514264337593543950336",
882        ] {
883            let mut direct = serde_json::Deserializer::from_str(token);
884            assert!(serialization::deserialize_decimal(&mut direct).is_err());
885            let value: Value = serde_json::from_str(token).unwrap();
886            assert!(serialization::deserialize_decimal(value.clone()).is_err());
887            assert!(serialization::deserialize_optional_decimal(value).is_err());
888        }
889    }
890
891    #[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
892    struct StringDecimal(
893        #[serde(
894            deserialize_with = "decimal::deserialize",
895            serialize_with = "serialization::serialize_decimal_as_str"
896        )]
897        Decimal,
898    );
899
900    proptest! {
901        #[rstest]
902        fn prop_checked_integer_visitors(
903            signed in prop_oneof![Decimal::MIN.mantissa()..=Decimal::MAX.mantissa(), any::<i128>()],
904            unsigned in prop_oneof![0..=Decimal::MAX.mantissa().unsigned_abs(), any::<u128>()],
905        ) {
906            let expected = Decimal::from_str_exact(&signed.to_string()).ok();
907            prop_assert_eq!(decimal::deserialize(I128Deserializer::<Error>::new(signed)).ok(), expected);
908            prop_assert_eq!(serialization::deserialize_decimal(I128Deserializer::<Error>::new(signed)).ok(), expected);
909            let expected = Decimal::from_str_exact(&unsigned.to_string()).ok();
910            prop_assert_eq!(decimal::deserialize(U128Deserializer::<Error>::new(unsigned)).ok(), expected);
911            prop_assert_eq!(serialization::deserialize_decimal(U128Deserializer::<Error>::new(unsigned)).ok(), expected);
912        }
913
914        #[rstest]
915        fn prop_roundtrips_and_exponent_rescaling(
916            mantissa in Decimal::MIN.mantissa()..=Decimal::MAX.mantissa(),
917            scale in 0u32..=Decimal::MAX_SCALE,
918            zeros in 0usize..=35,
919        ) {
920            let expected = Decimal::try_from_i128_with_scale(mantissa, scale).unwrap();
921            let scientific = format!("{mantissa}{}e-{}", "0".repeat(zeros), scale as usize + zeros);
922            prop_assert_eq!(decimal::parse(&scientific).unwrap(), expected);
923            prop_assert_eq!(serde_json::from_str::<Raw>(&scientific).unwrap(), Raw(expected));
924            let mut plain = expected.to_string();
925            if !plain.contains('.') { plain.push('.'); }
926            plain.push_str(&"0".repeat(zeros));
927            prop_assert_eq!(decimal::parse(&plain).unwrap(), expected);
928            let string = serde_json::to_value(StringDecimal(expected)).unwrap();
929            prop_assert_eq!(serde_json::from_value::<StringDecimal>(string).unwrap(), StringDecimal(expected));
930            if let Ok(number) = serde_json::to_value(Exact(expected)) {
931                prop_assert_eq!(decimal::parse(&number.to_string()).unwrap(), expected);
932                prop_assert_eq!(serde_json::from_value::<Raw>(number).unwrap(), Raw(expected));
933            } else {
934                prop_assert!(!arbitrary_precision());
935            }
936        }
937
938        #[rstest]
939        fn prop_parse_never_panics(value in "\\PC{0,128}") {
940            let _ = decimal::parse(&value);
941        }
942    }
943}