Class ScyllaJSONWriter

JSON format implementation of IScyllaWriter that serializes values into valid JSON text using an internal StringBuilder for efficient string accumulation. Supports optional pretty-printing with configurable indentation.

Inheritance

object

ScyllaJSONWriter

Implements

IScyllaWriter

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Serialization

Assembly: ScyllaCore.dll

Syntax

public sealed class ScyllaJSONWriter : IScyllaWriter, IDisposable

Remarks

The writer maintains a depth counter and a comma-needs flag to automatically insert commas between object properties and array elements without requiring callers to track separators manually. The pretty-print path additionally emits newlines and indentation according to the current nesting depth.

Special float/double values: Because the JSON specification does not support IEEE 754 special values, NaN, PositiveInfinity, and NegativeInfinity are written as the quoted string sentinels "NaN", "Infinity", and "-Infinity". These sentinels are understood by ScyllaJSONReader's float and double read methods. Regular finite float values use the G9 format and double values use G17 to guarantee lossless round-trip representation.

String escaping: All characters that must be escaped in JSON are handled by the internal WriteEscapedString helper, including backslash, quote, control characters, and any character below ASCII space (written as \uXXXX).

Byte arrays: Byte arrays are Base64-encoded and written as quoted JSON strings, compatible with ReadBytes().

Writer instances are pooled by ScyllaSerialization. Prefer calling ToJSON<T>(T) rather than constructing writers directly in hot paths.

Constructors

ScyllaJSONWriter()

Initializes a new ScyllaJSONWriter with a fresh internal StringBuilder (initial capacity 1024 characters), compact output mode, and tab indentation. The writer is ready to accept write calls immediately.

Declaration

public ScyllaJSONWriter()

ScyllaJSONWriter(StringBuilder)

Initializes a new ScyllaJSONWriter that writes into the specified StringBuilder instance rather than creating its own. This allows the caller to share or pre-size the output buffer, which is useful when the writer is retrieved from an object pool that manages the buffer lifecycle.

Declaration

public ScyllaJSONWriter(StringBuilder output)

Parameters

Type	Name	Description
StringBuilder	output	The StringBuilder to write output into. If `null`, a new default-capacity buffer is created instead.

Methods

Configure(SerializationSettings)

Applies the specified SerializationSettings to this writer, updating the pretty-print flag and indentation string. Settings that are not relevant to the writer (such as reference handling) are ignored. Has no effect if settings is null.

Declaration

public void Configure(SerializationSettings settings)

Parameters

Type	Name	Description
SerializationSettings	settings	The serialization settings to apply. If `null`, the call is a no-op and existing writer settings remain unchanged.

Dispose()

Declaration

public void Dispose()

GetByteOutput()

Returns all accumulated output as a byte array. For JSON format this is the UTF-8 encoding of the JSON string returned by GetStringOutput(). For binary formats this is the raw binary output.

Declaration

public byte[] GetByteOutput()

Returns

Type	Description
byte[]	The complete serialized byte output accumulated since the last Reset() call, or an empty array if nothing has been written yet.

GetStringOutput()

Returns all accumulated output as a string. For text-based formats such as JSON this returns the complete serialized document. For binary formats implementations may return a Base64 or otherwise encoded string representation.

Declaration

public string GetStringOutput()

Returns

Type	Description
string	The complete serialized string output accumulated since the last Reset() call, or an empty string if nothing has been written yet.

Reset()

Clears all accumulated output and resets all internal state (depth counters, comma tracking, property flags) so that the writer can be reused for a new serialization operation without allocating a new instance. Typically called by the object pool's release callback in ScyllaSerialization.

Declaration

public void Reset()

SetOutput(StringBuilder)

Replaces the internal output StringBuilder with the specified instance. Any content already accumulated in the previous buffer is discarded. Use this when reusing a pooled writer with a caller-supplied or pooled buffer.

Declaration

public void SetOutput(StringBuilder output)

Parameters

Type	Name	Description
StringBuilder	output	The StringBuilder to write into going forward. If `null`, a new default-capacity buffer is created and used instead.

SetPrettyPrint(bool)

Sets whether the writer should produce human-readable indented JSON output or compact single-line output. Must be called before any write operations if the desired mode differs from the default (compact). Changing this mid-write may produce malformed output.

Declaration

public void SetPrettyPrint(bool prettyPrint)

Parameters

Type	Name	Description
bool	prettyPrint	`true` to emit newlines and indentation; `false` for compact output with no extra whitespace between tokens.

ToString()

Returns the complete JSON output accumulated in this writer as a string. Equivalent to calling GetStringOutput().

Declaration

public override string ToString()

Returns

Type	Description
string	The current JSON string contents of the output buffer.

Overrides

object.ToString()

WriteBool(bool)

Writes a boolean value to the output stream. In JSON this emits the literal true or false.

Declaration

public void WriteBool(bool value)

Parameters

Type	Name	Description
bool	value	The boolean value to write.

WriteByte(byte)

Writes an unsigned 8-bit integer to the output stream as a numeric literal.

Declaration

public void WriteByte(byte value)

Parameters

Type	Name	Description
byte	value	The byte value in the range [0, 255] to write.

WriteBytes(byte[])

Writes a raw byte array to the output stream. In JSON format the bytes are encoded as a Base64 string and surrounded by quotes, which can be decoded symmetrically by ReadBytes(). If bytes is null, emits a null literal.

Declaration

public void WriteBytes(byte[] bytes)

Parameters

Type	Name	Description
byte[]	bytes	The byte array to encode and write, or `null` to emit a null literal.

WriteChar(char)

Writes a single character to the output stream. The character is encoded as a single-character string value, including any required escape sequences for special characters (e.g., a tab character is written as "\t" in JSON).

Declaration

public void WriteChar(char value)

Parameters

Type	Name	Description
char	value	The character to write.

WriteDecimal(decimal)

Writes a high-precision decimal value to the output stream as a numeric literal, using invariant culture formatting to ensure locale independence.

Declaration

public void WriteDecimal(decimal value)

Parameters

Type	Name	Description
decimal	value	The decimal value to write.

WriteDouble(double)

Writes a double-precision floating-point number to the output stream. Because the JSON specification does not represent IEEE 754 special values natively, the values NaN, PositiveInfinity, and NegativeInfinity are written as the quoted string sentinels "NaN", "Infinity", and "-Infinity" respectively, which ReadDouble() can decode symmetrically. Regular finite values are written using the G17 format specifier to preserve round-trip precision.

Declaration

public void WriteDouble(double value)

Parameters

Type	Name	Description
double	value	The double value to write. May be NaN, PositiveInfinity, or NegativeInfinity.

WriteEndArray()

Writes the closing delimiter of an array structure to the output stream. In JSON this emits a ] character. Must be called once for every preceding WriteStartArray() call at the same nesting level.

Declaration

public void WriteEndArray()

WriteEndObject()

Writes the closing delimiter of an object structure to the output stream. In JSON this emits a } character. Must be called once for every preceding WriteStartObject() call at the same nesting level.

Declaration

public void WriteEndObject()

WriteFloat(float)

Writes a single-precision floating-point number to the output stream. Because the JSON specification does not represent IEEE 754 special values natively, the values NaN, PositiveInfinity, and NegativeInfinity are written as the quoted string sentinels "NaN", "Infinity", and "-Infinity" respectively, which ReadFloat() can decode symmetrically. Regular finite values are written using the G9 format specifier to preserve round-trip precision.

Declaration

public void WriteFloat(float value)

Parameters

Type	Name	Description
float	value	The float value to write. May be NaN, PositiveInfinity, or NegativeInfinity.

WriteInt(int)

Writes a 32-bit signed integer to the output stream as a numeric literal.

Declaration

public void WriteInt(int value)

Parameters

Type	Name	Description
int	value	The integer value in the range [-2147483648, 2147483647] to write.

WriteLong(long)

Writes a 64-bit signed integer to the output stream as a numeric literal.

Declaration

public void WriteLong(long value)

Parameters

Type	Name	Description
long	value	The long value in the range [-9223372036854775808, 9223372036854775807] to write.

WriteNull()

Writes a null literal to the output stream. In JSON this emits the four characters null. Callers should invoke this when the value to write is a null reference rather than calling a typed write method with a null argument.

Declaration

public void WriteNull()

WritePropertyName(string)

Writes a property name key to the output stream. In JSON this emits the name as a quoted and escaped string followed by a colon separator. Must be called immediately before the corresponding value write method. Handles comma insertion between consecutive properties automatically.

Declaration

public void WritePropertyName(string name)

Parameters

Type	Name	Description
string	name	The property name to write. Must not be `null`. Any characters that require JSON escaping are escaped automatically.

WriteRawValue(string)

Writes an already-encoded value verbatim, with no quoting, escaping or reformatting. Separator and indentation handling still applies, so the value is placed correctly within the surrounding object or array.

Declaration

public void WriteRawValue(string rawValue)

Parameters

Type	Name	Description
string	rawValue	The pre-encoded value text to emit. Must not be `null` or empty.

Remarks

This exists for callers that must reproduce a value's exact original text rather than a round-tripped rendering of its parsed form. The motivating case is lossless re-serialization of a document that was parsed from another tool's output: writing a stored numeric lexeme back out guarantees that 1 stays 1 and never becomes 1.0, and sidesteps the culture sensitivity of the integer overloads.

The caller is responsible for the content being valid in the target format. Nothing is validated or escaped. Prefer a typed Write* method whenever one applies.

Exceptions

Type	Condition
ArgumentException	Thrown when `rawValue` is `null` or empty, which would emit nothing where a value is required and produce malformed JSON.

WriteSByte(sbyte)

Writes a signed 8-bit integer to the output stream as a numeric literal.

Declaration

public void WriteSByte(sbyte value)

Parameters

Type	Name	Description
sbyte	value	The signed byte value in the range [-128, 127] to write.

WriteShort(short)

Writes a 16-bit signed integer to the output stream as a numeric literal.

Declaration

public void WriteShort(short value)

Parameters

Type	Name	Description
short	value	The short value in the range [-32768, 32767] to write.

WriteStartArray()

Writes the opening delimiter of an array structure to the output stream. In JSON this emits a [ character. Must be paired with a subsequent call to WriteEndArray(). Array and object structures may be nested.

Declaration

public void WriteStartArray()

WriteStartObject()

Writes the opening delimiter of an object structure to the output stream. In JSON this emits a { character. Must be paired with a subsequent call to WriteEndObject(). Object and array structures may be nested.

Declaration

public void WriteStartObject()

WriteString(string)

Writes a string value to the output stream, applying all necessary escape sequences for special characters (e.g., ", \, \n, \r, \t, and \uXXXX for control characters). If value is null, emits a null literal instead of a quoted string.