error.rs

Overview

[error.rs](/projects/287/67767) defines the `DeserializeError` struct and its associated methods, which represent errors encountered during JSON deserialization in the project. This file provides a unified error representation tailored to handle two different JSON parsing backends controlled via Cargo features: the default parser (non-`yyjson`) and the `yyjson` parser.

The primary purpose of this file is to encapsulate error information, including descriptive messages and precise error locations within the input data, to aid debugging and error reporting during deserialization workflows.

Detailed Documentation

Struct: DeserializeError<'a>

Represents an error encountered while deserializing JSON data.

Fields

• message: Cow<'a, str>
  Human-readable error message describing the cause of the deserialization failure.

• line: usize (only present when the feature yyjson is not enabled)
  The 1-based line number where the error occurred in the input JSON.

• column: usize (only present when the feature yyjson is not enabled)
  The 1-based column number (character offset in the line) where the error occurred.

• data: Option<&'a str>
  An optional reference to the original JSON string slice being parsed. This is used to compute error positions.

• pos: i64 (only present when the feature yyjson is enabled)
  The byte offset position of the error in the JSON data, specific to the yyjson parser.

Associated Methods

invalid(message: Cow<'a, str>) -> Self

Creates a generic `DeserializeError` with an invalid or unspecified position.

• Parameters

  • message: The error message describing the error.

• Returns
  A DeserializeError instance with zeroed position information.

• Usage Example

let err = DeserializeError::invalid(Cow::from("Invalid JSON format"));
println!("{}", err.message);

from_json(message: Cow<'a, str>, line: usize, column: usize, data: &'a str) -> Self

*(Only available if `yyjson` feature is NOT enabled)*

Creates a `DeserializeError` from a JSON parser that tracks line and column positions.

• Parameters

  • message: Error message.

  • line: Line number (1-based) where the error occurred.

  • column: Column number (1-based) where the error occurred.

  • data: The original JSON string slice.

• Returns
  A DeserializeError instance populated with line/column info.

• Usage Example

let err = DeserializeError::from_json(
    Cow::from("Unexpected token"),
    12,
    5,
    r#"{"key": "value", "bad_json": [1, 2,}"#,
);

from_yyjson(message: Cow<'a, str>, pos: i64, data: &'a str) -> Self

*(Only available if `yyjson` feature IS enabled)*

Creates a `DeserializeError` from the `yyjson` parser error positional information.

• Parameters

  • message: Error message.

  • pos: Byte offset position of the error in the JSON data.

  • data: The original JSON string slice.

• Returns
  A DeserializeError instance with the yyjson specific position.

• Usage Example

let err = DeserializeError::from_yyjson(
    Cow::from("Invalid character"),
    45,
    r#"{"key": "value", "bad_json": [1, 2,}"#,
);

pos(&self) -> i64

Returns the error position as a character offset within the JSON data.

• Returns
  The character offset position of the error in the input JSON string.

  • For yyjson feature: counts characters up to the byte offset pos.

  • For non-yyjson: computes character offset based on line and column, taking care to handle UTF-8 character boundaries.

• Implementation Details

  • yyjson variant:
    Counts characters from the start of the string slice data up to the byte offset pos.

  • Non-yyjson variant:
    Splits the JSON string by newlines, sums character counts of all lines before the error line, and then counts characters up to the error column in the error line, carefully adjusting for UTF-8 boundaries.

• Usage Example

let position = error.pos();
println!("Error at character offset: {}", position);

Important Implementation Details and Algorithms

• Conditional Compilation:
  The struct conditionally includes fields and methods depending on whether the yyjson feature is enabled, allowing for compatibility with different JSON parsing backends without duplicating codebases.

• UTF-8 Boundary Handling:
  The non-yyjson pos() method carefully computes the character offset by accounting for UTF-8 multibyte characters, ensuring the column-based error position corresponds correctly to character indices rather than byte indices.

• Cow<'a, str> Usage:
  The message field uses Cow<'a, str> to efficiently represent error messages that may either be borrowed or owned, optimizing memory use and performance.

• #[cold] Attribute:
  The methods are marked with #[cold] to hint to the compiler that these paths are unlikely to be hit (errors are exceptional), allowing for optimized instruction cache use and branch prediction.

Interaction with Other Parts of the System

• Deserialization Workflow:
  This file is part of the deserialization module that processes JSON input. When parsing fails, instances of DeserializeError are created and propagated to higher layers for error handling and reporting.

• Conditional Feature Support:
  Based on Cargo features, this error type bridges error reporting between the default JSON parser and the yyjson parser.

• Error Reporting and Logging:
  The error messages and positional information produced by DeserializeError instances are likely logged or presented to users/developers to facilitate debugging malformed JSON inputs.

Mermaid Diagram: Structure of DeserializeError

classDiagram
    class DeserializeError<'a> {
        +message: Cow<'a, str>
        +line: usize [conditional, no "yyjson"]
        +column: usize [conditional, no "yyjson"]
        +data: Option<&'a str>
        +pos: i64 [conditional, "yyjson"]
        +invalid(message: Cow<'a, str>) DeserializeError<'a>
        +from_json(message: Cow<'a, str>, line: usize, column: usize, data: &'a str) DeserializeError<'a> [conditional, no "yyjson"]
        +from_yyjson(message: Cow<'a, str>, pos: i64, data: &'a str) DeserializeError<'a> [conditional, "yyjson"]
        +pos() i64
    }

Summary

The [error.rs](/projects/287/67767) file provides a crucial abstraction for JSON deserialization errors, unifying error details across multiple JSON parsing backends with precise location tracking. It is implemented with careful attention to UTF-8 correctness and performance considerations and integrates seamlessly into the broader deserialization and error handling framework of the system.