Class ScyllaBinaryWriter

Binary format implementation of IScyllaWriter that serializes values into a compact tagged byte stream. Every value and structural delimiter is preceded by a single BinaryTypeTag byte, which ScyllaBinaryReader reads back to validate structure instead of trusting position alone.

Inheritance

object

ScyllaBinaryWriter

Implements

IScyllaWriter

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Serialization

Assembly: ScyllaCore.dll

Syntax

public sealed class ScyllaBinaryWriter : IScyllaWriter, IDisposable

Remarks

All multi-byte primitives are written little-endian, unconditionally, so a value written on one platform reads correctly on another regardless of native endianness. Integers go through BinaryPrimitives; float and double go through BitConverter instead, because this Unity BCL profile does not expose BinaryPrimitives.WriteSingleLittleEndian or WriteDoubleLittleEndian (only the integer overloads are available). The Core assembly declares allowUnsafeCode: false, so nothing here uses pointer writes.

Floating-point values: unlike the JSON writer, NaN, PositiveInfinity and NegativeInfinity (and their double counterparts) need no string-sentinel encoding here, because the binary format stores the native IEEE 754 bit pattern directly.

Arrays: WriteStartArray() writes only a StartArray tag, the same as ScyllaJSONWriter writes no element count up front, because the underlying WriteStartArray() contract carries no count parameter. GetArrayLength() therefore also returns -1, which the interface documents as the correct value when the count is not available up front.

WriteRawValue(string) throws NotSupportedException. It exists on IScyllaWriter only to reproduce another tool's exact source text for a numeric lexeme, which has no meaning for a binary format and, as of this writing, has no callers anywhere in the framework outside the JSON writer's own implementation.

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

Constructors

ScyllaBinaryWriter()

Initializes a new ScyllaBinaryWriter with a fresh internal buffer (initial capacity 1024 bytes). The writer is ready to accept write calls immediately.

Declaration

public ScyllaBinaryWriter()

Methods

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

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.

Remarks

See the remarks on WriteFloat(float); the same BitConverter-based fallback applies here.

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.

Remarks

Written via GetBytes(float) rather than BinaryPrimitives.WriteSingleLittleEndian, which this Unity BCL profile does not expose (only the integer overloads are available). The bytes are reversed on a big-endian host so the on-wire representation stays little-endian regardless.

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.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `name` is `null`.

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
NotSupportedException	Always thrown. A binary stream has no textual lexeme to reproduce verbatim; use a typed `Write*` method instead.

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.