Enum JsonConversionError 

pub enum JsonConversionError {
    ParseError(String),
    InvalidRoot(String),
    InvalidNumber(String),
    InvalidExpression(String),
    InvalidTensor,
    NestedObject,
    InvalidReference(String),
    InvalidUnicode(String),
    MaxDepthExceeded(usize),
    MaxArraySizeExceeded(usize, usize),
    MaxStringLengthExceeded(usize, usize),
    MaxObjectSizeExceeded(usize, usize),
    IntegerOverflow {
        value: String,
        max: i64,
        min: i64,
    },
}

Errors that can occur during JSON to HEDL conversion

Variants

ParseError(String)

JSON parsing failed

InvalidRoot(String)

Root value must be an object

InvalidNumber(String)

Invalid number value

InvalidExpression(String)

Invalid expression syntax

InvalidTensor

Invalid tensor element

NestedObject

Nested objects not allowed in scalar context

InvalidReference(String)

Reference parsing failed

InvalidUnicode(String)

Invalid Unicode encoding

This error occurs when JSON contains invalid Unicode sequences, such as:

• Unpaired UTF-16 surrogates (\uD83D without its low surrogate pair)
• Invalid surrogate pairs (low surrogate before high surrogate)
• Unescaped control characters in strings

UTF-16 Surrogate Background

JSON’s \uXXXX escapes use UTF-16 encoding. Characters outside the Basic Multilingual Plane (U+10000 and above, including emoji) require surrogate pairs: a high surrogate (0xD800-0xDBFF) followed by a low surrogate (0xDC00-0xDFFF).

Solutions

1. Use the SurrogatePolicy::ReplaceWithFFFD option: Replace invalid surrogates with the Unicode replacement character.

2. Preprocess the JSON to fix or remove invalid sequences.

3. Ensure the source system produces valid UTF-8/UTF-16 pairs.

MaxDepthExceeded(usize)

Maximum recursion depth exceeded

MaxArraySizeExceeded(usize, usize)

Maximum array size exceeded

MaxStringLengthExceeded(usize, usize)

Maximum string length exceeded

MaxObjectSizeExceeded(usize, usize)

Maximum object size exceeded

IntegerOverflow

Integer value outside i64 range

JSON supports arbitrary-precision numbers, but HEDL’s Value::Int uses i64 which has a fixed range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

Common Causes

• Twitter/Snowflake IDs (often exceed i64::MAX)
• Unsigned 64-bit integers from other systems
• Large database auto-increment IDs
• Timestamps in nanoseconds beyond year 2262

Solutions

1. Use strings for large IDs (recommended):

   {"tweet_id": "18446744073709551615"}

2. Use hex encoding:

   {"large_number": "0xFFFFFFFFFFFFFFFF"}

3. Split into high/low parts:

   {"value_high": 1844674407, "value_low": 3709551615}

Examples

use hedl_json::{from_json, FromJsonConfig};

let json = r#"{"id": 18446744073709551615}"#;
let result = from_json(json, &FromJsonConfig::default());

assert!(result.is_err());
assert!(result.unwrap_err().to_string().contains("Integer overflow"));

Fields

value: String

String representation of the overflowing value.

max: i64

Maximum valid i64 value.

min: i64

Minimum valid i64 value.

Trait Implementations

impl Clone for JsonConversionError

fn clone(&self) -> JsonConversionError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JsonConversionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for JsonConversionError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for JsonConversionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for JsonConversionError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<JsonConversionError> for StreamError

fn from(source: JsonConversionError) -> Self

Converts to this type from the input type.