Interface IScyllaWriter

Low-level, format-agnostic interface for writing serialized data in a sequential, value-by-value fashion. Implementations encode values into a specific wire format (such as JSON) so that the serialization engine can produce output without being coupled to the underlying representation.

Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaWriter : IDisposable
Remarks

Writers are stateful and accumulate output internally as write methods are called. The complete result is retrieved via GetStringOutput() or GetByteOutput() once all values have been written. Calling Reset() discards all accumulated output and returns the writer to its initial state, enabling reuse without allocation.

The expected call pattern for writing an object is:

  1. Call WriteStartObject().
  2. For each property: call WritePropertyName(string) followed immediately by the appropriate Write* method for the value.
  3. Call WriteEndObject().

For arrays, replace steps 1 and 3 with WriteStartArray() and WriteEndArray(), and omit WritePropertyName(string) calls.

Writers are typically obtained from an object pool managed by ScyllaSerialization. Prefer calling ToJSON<T>(T) rather than using writers directly in most cases.

Implementations must throw SerializationException when an illegal write sequence is detected (e.g., writing a property value without a preceding WritePropertyName(string) call).

Methods

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
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
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
void Reset()

WriteBool(bool)

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

Declaration
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
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
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
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
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
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
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
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
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
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
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
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
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
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.

WriteSByte(sbyte)

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

Declaration
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
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
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
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.

Declaration
void WriteString(string value)
Parameters
Type Name Description
string value

The string value to write, or null to emit a null literal.

WriteUInt(uint)

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

Declaration
void WriteUInt(uint value)
Parameters
Type Name Description
uint value

The unsigned integer value in the range [0, 4294967295] to write.

WriteULong(ulong)

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

Declaration
void WriteULong(ulong value)
Parameters
Type Name Description
ulong value

The unsigned long value in the range [0, 18446744073709551615] to write.

WriteUShort(ushort)

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

Declaration
void WriteUShort(ushort value)
Parameters
Type Name Description
ushort value

The unsigned short value in the range [0, 65535] to write.

Extension Methods

See Also