Struct JcsEncoder 

pub struct JcsEncoder<'budget, R = JsonResource, Q = usize>
where
    Q: ResourceQuantity,
{ /* private fields */ }

Encodes serde_json::Value values using RFC 8785 canonical JSON.

JCS uses an IEEE 754 binary64 number model. Integer values outside the exactly representable range can therefore be rounded (for example, 9007199254740993 becomes 9007199254740992). Output limits measure the final canonical byte sequence. Auxiliary storage used while rendering is limited separately by max_working_bytes; this limit covers the renderer’s traversal stack and active object member tables, but excludes the input Value, buffered output bytes, and any admission stack used to check configured value limits before rendering. Configure max_depth as well when the admission traversal itself must have a depth bound. A working memory limit is a capacity bound for these renderer collections, not an exact heap-usage bound.

Type Parameters

• 'budget - Lifetime of the resource budget borrowed by the encoder session.
• R - Resource identity type tracked by the session.
• Q - Quantity type used for resource limits and accounting.

Examples

use qubit_json::encode::JcsEncoder;

let mut encoder = JcsEncoder::unlimited();
let bytes = encoder.to_vec(&serde_json::json!({"b": 2, "a": 1.0}))?;
assert_eq!(bytes, br#"{"a":1,"b":2}"#);

Implementations

impl<R, Q> JcsEncoder<'static, R, Q>

where R: Clone + Debug, Q: ResourceQuantity,

pub fn with_limits( limits: JsonEncodeLimits<R, Q>, max_working_bytes: usize, ) -> Self

Creates an encoder with an owned session using limits.

max_working_bytes caps the capacity of the renderer’s traversal stack and active object member tables.

Type Parameters

• R - Resource identity type tracked by the session.
• Q - Quantity type used for resource limits and accounting.

Parameters

• limits supplies cumulative value and output limits.
• max_working_bytes limits auxiliary traversal and member-table memory.

Returns

An encoder that owns a session initialized from limits.

impl JcsEncoder<'static, JsonResource, usize>

pub fn unlimited() -> Self

Creates an encoder with effectively unlimited value, output, and working memory limits.

Returns

An encoder backed by a fresh session without configured resource limits.

impl<'budget, R, Q> JcsEncoder<'budget, R, Q>

where R: Clone + Debug, Q: ResourceQuantity,

pub fn new( session: JsonEncodeSession<'budget, R, Q>, max_working_bytes: usize, ) -> Self

Creates an encoder that retains the supplied cumulative session.

max_working_bytes caps the capacity of the renderer’s traversal stack and active object member tables.

Type Parameters

• 'budget - Lifetime of the resource budget borrowed by session.
• R - Resource identity type tracked by session.
• Q - Quantity type used for resource limits and accounting.

Parameters

• session is the cumulative accounting session to retain.
• max_working_bytes limits auxiliary traversal and member-table memory.

Returns

An encoder using the supplied session and working-memory limit.

pub const fn max_working_bytes(&self) -> usize

Returns the maximum auxiliary working memory in bytes.

Returns

The configured maximum working-memory capacity.

pub const fn session(&self) -> &JsonEncodeSession<'budget, R, Q>

Returns the cumulative accounting session.

Returns

A shared reference to this encoder’s session.

pub const fn session_mut(&mut self) -> &mut JsonEncodeSession<'budget, R, Q>

Returns mutable access to the cumulative accounting session.

Returns

A mutable reference to this encoder’s session.

pub fn into_session(self) -> JsonEncodeSession<'budget, R, Q>

Consumes the encoder and returns its cumulative accounting session.

Returns

The session containing the cumulative resource accounting state.

pub fn to_vec(&mut self, value: &Value) -> Result<Vec<u8>, JcsEncodeError<R, Q>>

Encodes a value and commits its accounting only after full success.

Parameters

• value is the JSON value to encode.

Returns

The complete canonical JSON bytes on success.

Errors

Returns JcsEncodeError if rendering, memory allocation, or resource accounting fails. The value and output accounting is committed only on success.

pub fn to_string( &mut self, value: &Value, ) -> Result<String, JcsEncodeError<R, Q>>

Encodes a value as UTF-8 text, committing only after successful encoding.

Parameters

• value is the JSON value to encode.

Returns

The complete canonical JSON document as a UTF-8 string.

Errors

Returns JcsEncodeError if encoding or resource accounting fails.

Panics

Panics only if the renderer produces bytes that are not valid UTF-8, which violates the encoder’s JSON output invariant.

pub fn write_buffered<O: ByteOutput + ?Sized>( &mut self, output: &mut O, value: &Value, ) -> Result<(), JcsEncodeError<R, Q>>

Buffers the canonical document before writing it to output.

Output budget is checked against the complete document before external I/O. If the destination fails, accepted bytes remain written and remain charged, while the value transaction is not committed. This method does not flush the destination. Success means that the destination accepted the complete document and the encoding charges were committed. The writer is borrowed mutably for this call; flush it explicitly afterward. A later flush is outside this encoding transaction and does not roll back committed charges if it fails. Do not rely on Drop to report flush errors. A successful flush does not guarantee durability or delivery to a remote peer.

Type Parameters

• O - Output destination receiving the complete buffered document.

Parameters

• output is borrowed mutably and receives the complete document.
• value is the JSON value to encode.

Returns

Ok(()) after the destination has accepted all bytes and accounting is committed. The destination is not flushed.

Errors

Returns JcsEncodeError if rendering, output budgeting, destination I/O, or session accounting fails. A destination failure preserves accepted output bytes and their output charges without committing the value transaction. A later caller-initiated flush failure does not undo the already committed charges.

Examples

use std::io::BufWriter;
use std::io::Write;

use qubit_budget::json::JsonEncodeLimits;
use qubit_budget::json::JsonResource;
use qubit_json::encode::JcsEncoder;
use serde_json::json;

let limits = JsonEncodeLimits::<JsonResource, usize>::builder()
    .max_output_bytes(64)
    .build();
let mut encoder = JcsEncoder::with_limits(limits, 16 * 1024);
let mut writer = BufWriter::new(Vec::new());
encoder.write_buffered(&mut writer, &json!({"b": 2, "a": 1}))?;
writer.flush()?;
let bytes = writer.into_inner().expect("flush already succeeded");
assert_eq!(bytes, br#"{"a":1,"b":2}"#);

pub fn write_incremental<O: ByteOutput + ?Sized>( &mut self, output: &mut O, value: &Value, ) -> Result<(), JcsEncodeError<R, Q>>

Writes canonical output directly to output as it is produced.

Accepted bytes are charged immediately and remain written if rendering, flushing, or destination I/O later fails. A failed operation does not commit the value budget. On success, this method flushes the destination before committing value accounting; a flush failure therefore retains charges for accepted output bytes without committing the value budget. The destination is borrowed mutably for this call.

Type Parameters

• O - Output destination receiving bytes as they are rendered.

Parameters

• output is borrowed mutably and receives bytes as they are rendered.
• value is the JSON value to encode.

Returns

Ok(()) after rendering, flushing, and accounting all succeed.

Errors

Returns JcsEncodeError if rendering, working-memory allocation, destination I/O, or session accounting fails. Accepted output bytes remain written and charged, while failed operations do not commit the value budget.