Module

std::serializer::core

Serializer Core

Format-agnostic serializer helpers shared by front-ends and user records.

Overview

Core helpers implement the state-free operations needed by JSON and TOML serialization: opening and closing records, writing field names, escaping text, validating bare keys, and appending scalar text. The caller owns all ordering decisions; this module only appends the requested bytes to the destination.

Record Emission Flow

A typical Serialize implementation uses these helpers in this order:

  beginRecord(output, writer)
       │
       ├─ writeField(output, "first", writer, true)
       │       └─ Serializer::write(output, value, writer)
       │
       ├─ writeField(output, "second", writer, false)
       │       └─ Serializer::write(output, value, writer)
       │
       └─ endRecord(output, writer)

The first flag controls whether the writer’s entrySeparator is emitted before a field. The core helpers do not track field count internally.

Escaping

writeQuotedString and writeQuotedChar use byte-oriented escaping. Quotes, backslashes, newlines, carriage returns, tabs, and ASCII control bytes are escaped. Other bytes are written through as UTF-8 bytes stored in Ignis String values.

namespace Serializer

Format-neutral serialization primitives shared by JSON and TOML front-ends.

The namespace contains the Writer configuration record and low-level helpers used by generated or handwritten Serialize implementations.

Records

record Writer

Format configuration consumed by serializer helpers.

JSON and TOML differ mostly in punctuation and root-shape policy. A writer stores those differences so scalar and record code can stay format-neutral.

Members

recordPrefix: str

Text appended before a serialized record, for example { for JSON.

recordSuffix: str

Text appended after a serialized record, for example } for JSON.

entrySeparator: str

Text inserted between record entries after the first field.

fieldSeparator: str

Text inserted between a field key and its value.

supportsScalarRoot: boolean

Whether the front-end permits a scalar value as the document root.

quoteFieldKeys: boolean

Whether field keys are always emitted as quoted strings.

Functions

function beginRecord(output: &mut String, serializer: &Writer): Result<boolean, Error>

Appends the writer’s record prefix to output.

Returns Result::OK(true) for consistency with the rest of the serializer API. This function does not validate that a matching endRecord is later called.

Example

let writer: Serializer::Writer = Json::writer();
let mut output: String = String::new();
Serializer::beginRecord(&mut output, &writer)!; // appends "{"

function endRecord(output: &mut String, serializer: &Writer): Result<boolean, Error>

Appends the writer’s record suffix to output.

Call this after all fields have been written. The helper does not check whether the record is empty or whether field separators were used correctly.

Example

let writer: Serializer::Writer = Json::writer();
let mut output: String = String::create("{");
Serializer::endRecord(&mut output, &writer)!; // appends "}"

function hexDigit(value: u8): char

Converts a four-bit value into an uppercase hexadecimal digit.

writeEscapedByte uses this for \u00XX control-byte escapes. Values should be in the inclusive range 0..15.

Example

let digit: char = Serializer::hexDigit(10); // 'A'

function isBareKeyByte(byte: u8): boolean

Returns whether one byte is accepted by isValidBareKey.

Accepted bytes are ASCII letters, ASCII digits, _, and -.

Example

let letter: boolean = Serializer::isBareKeyByte('a' as u8);
let dot: boolean = Serializer::isBareKeyByte('.' as u8); // false

function isValidBareKey(key: str): boolean

Returns whether key is valid as an unquoted serializer field key.

Bare keys are currently restricted to non-empty ASCII letters, digits, underscores, and hyphens. This matches TOML’s common bare-key subset and avoids ambiguous output in front-ends that do not quote field names.

Example

let ok: boolean = Serializer::isValidBareKey("package-name");
let bad: boolean = Serializer::isValidBareKey("package.name");

function writeEscapedByte(output: &mut String, byte: u8): void

Writes one string byte, escaping bytes that require quoted-string syntax.

This helper assumes the caller has already written the surrounding quotes. It emits JSON-compatible escapes for quotes, backslashes, common whitespace, and ASCII control bytes.

Example

let mut output: String = String::new();
Serializer::writeEscapedByte(&mut output, ('\t' as u8));
// output contains "\\t"

function writeField(output: &mut String, key: str, serializer: &Writer, first: boolean): Result<boolean, Error>

Writes a field key and separator for the next record entry.

If first is false, the writer’s entrySeparator is emitted before the key. When quoteFieldKeys is enabled, the key is escaped as a quoted string. Otherwise the key must be a non-empty ASCII bare key containing only letters, digits, _, or -; invalid keys return Serializer::ErrorKind::INVALID_FIELD_KEY.

Arguments

output: destination record text.
key: field name to emit.
serializer: writer configuration that controls quoting and separators.
first: whether this is the first field in the record.

Example

let writer: Serializer::Writer = Json::writer();
let mut output: String = String::create("{");
Serializer::writeField(&mut output, "name", &writer, true)!;
// output now contains "{\"name\":"

function writeQuotedChar(output: &mut String, value: char): void

Writes one quoted character using serializer string escaping rules.

The character is emitted between double quotes. Special byte values are escaped through writeEscapedByte.

Example

let mut output: String = String::new();
Serializer::writeQuotedChar(&mut output, '\n');
// output contains "\n"

function writeQuotedString(output: &mut String, value: &String): void

Writes a quoted string using byte-oriented serializer escaping rules.

The input is not modified. Escaping is shared by JSON and TOML front-ends, so it intentionally covers the common JSON-compatible escape set.

Example

let mut output: String = String::new();
let value: String = String::create("line\nquoted");
Serializer::writeQuotedString(&mut output, &value);

function writeScalarText(output: &mut String, text: &String): Result<boolean, Error>

Appends already-formatted scalar text to output.

Numeric and boolean write overloads convert to text before calling this helper. The text is not quoted or escaped here.

Example

let mut output: String = String::new();
let text: String = String::create("42");
Serializer::writeScalarText(&mut output, &text)!;

Functions

function __closure_thunk_0(__closure_env_0: *mut u8, byte: u8): void