Class ScyllaBinaryReader

Binary format implementation of IScyllaReader that parses a tagged byte stream produced by ScyllaBinaryWriter in a forward-only, token-by-token fashion, mirroring the parsing model ScyllaJSONReader uses for JSON.

Inheritance
object
ScyllaBinaryReader
Implements
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaBinaryReader : IScyllaReader, IDisposable
Remarks

Every read method except PeekToken() validates that the tag at the current position matches the type being read, and throws SerializationException on a mismatch. This is stricter than ScyllaJSONReader, which erases integer width entirely (every JSON integer read parses via long internally), because every built-in type serializer writes and reads a given value through the same-named Write*/Read* pair, so a tag mismatch reliably indicates either data corruption or a caller reading the wrong member.

All multi-byte primitives are read little-endian, unconditionally. Integers go through BinaryPrimitives; float and double go through BitConverter instead, because this Unity BCL profile does not expose BinaryPrimitives.ReadSingleLittleEndian or ReadDoubleLittleEndian (only the integer overloads are available).

GetArrayLength() always returns -1. See the remarks on ScyllaBinaryWriter for why the format carries no element count.

ReadNumberLexeme() throws NotSupportedException, for the same reason WriteRawValue(string) does: a binary stream has no textual lexeme to reproduce, and the method has no callers anywhere in the framework outside the JSON reader's own implementation.

Reader instances are pooled by ScyllaSerialization. Prefer calling FromBytes<T>(byte[], SerializationSettings) rather than constructing readers directly in hot paths.

Constructors

ScyllaBinaryReader()

Initializes a new ScyllaBinaryReader with no input data. Call Reset(byte[]) before reading.

Declaration
public ScyllaBinaryReader()

ScyllaBinaryReader(byte[])

Initializes a new ScyllaBinaryReader and sets the specified binary data as the initial input. The reader is ready to begin reading immediately.

Declaration
public ScyllaBinaryReader(byte[] data)
Parameters
Type Name Description
byte[] data

The binary data to parse. Passing null is treated as empty input.

Properties

HasMore

Gets a value indicating whether the reader has additional tokens remaining in the input stream. Returns false when the entire input has been consumed, meaning PeekToken() would return None.

Declaration
public bool HasMore { get; }
Property Value
Type Description
bool

true if there are unread tokens in the current input; false if the read position has reached or passed the end of the input.

Methods

Dispose()

Declaration
public void Dispose()

GetArrayLength()

Returns the number of elements in the current array, if the underlying format encodes this count up front (e.g., binary formats). Must be called after ReadStartArray() and before reading any elements.

Declaration
public int GetArrayLength()
Returns
Type Description
int

The number of elements in the array, or -1 if the count is not available up front (as is the case with JSON, which does not encode array length). When -1 is returned, callers should iterate until EndArray is encountered via PeekToken().

PeekToken()

Inspects the type of the next token in the input stream without consuming it or advancing the read position. Callers should use this to branch between value types before calling the appropriate Read* method.

Declaration
public SerializationToken PeekToken()
Returns
Type Description
SerializationToken

A SerializationToken value describing the next available token, or None if the stream is exhausted.
Exceptions
Type Condition
SerializationException

Thrown if the input contains an unexpected character at the current position that cannot be mapped to any known token type.

ReadBool()

Reads and consumes a boolean value from the input stream.

Declaration
public bool ReadBool()
Returns
Type Description
bool

The boolean value: true or false.
Exceptions
Type Condition
SerializationException

Thrown if the next token in the stream is not a valid boolean literal.

ReadByte()

Reads and consumes an unsigned 8-bit integer value from the input stream. The value is parsed from an integer token and cast to byte.

Declaration
public byte ReadByte()
Returns
Type Description
byte

The byte value in the range [0, 255].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadBytes()

Reads and consumes a raw byte array from the input stream. In JSON format, byte arrays are encoded as Base64 strings and decoded back to their binary form upon reading.

Declaration
public byte[] ReadBytes()
Returns
Type Description
byte[]

The decoded byte array, or null if the next token is a null literal.
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a string literal and is not a null literal.

ReadChar()

Reads and consumes a single character from the input stream. The character is typically stored as a single-character string in the underlying format. If the encoded string is empty, the null character ('\0') is returned.

Declaration
public char ReadChar()
Returns
Type Description
char

The character value, or '\0' if the encoded string is null or empty.
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid string literal.

ReadDecimal()

Reads and consumes a high-precision decimal value from the input stream. The value is parsed using invariant culture formatting to ensure locale independence.

Declaration
public decimal ReadDecimal()
Returns
Type Description
decimal

The decimal value.
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadDouble()

Reads and consumes a double-precision floating-point number from the input stream. Implementations must handle the special string-encoded values "NaN", "Infinity", and "-Infinity", which are used because JSON does not natively represent IEEE 754 special values.

Declaration
public double ReadDouble()
Returns
Type Description
double

The double value, which may be NaN, PositiveInfinity, or NegativeInfinity if the corresponding string-encoded sentinel was present in the stream.
Remarks

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

Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal or a recognized special-value string.

ReadEndArray()

Reads and consumes the closing delimiter of an array structure, advancing the read cursor past it. In JSON this is the ] character. Call this after all elements of an array have been read.

Declaration
public void ReadEndArray()
Exceptions
Type Condition
SerializationException

Thrown if the next token is not the end of an array structure.

ReadEndObject()

Reads and consumes the closing delimiter of an object structure, advancing the read cursor past it. In JSON this is the } character. Call this after all properties of an object have been read.

Declaration
public void ReadEndObject()
Exceptions
Type Condition
SerializationException

Thrown if the next token is not the end of an object structure.

ReadFloat()

Reads and consumes a single-precision floating-point number from the input stream. Implementations must handle the special string-encoded values "NaN", "Infinity", and "-Infinity", which are used because JSON does not natively represent IEEE 754 special values.

Declaration
public float ReadFloat()
Returns
Type Description
float

The float value, which may be NaN, PositiveInfinity, or NegativeInfinity if the corresponding string-encoded sentinel was present in the stream.
Remarks

Read via ToSingle(byte[], int) rather than BinaryPrimitives.ReadSingleLittleEndian, which this Unity BCL profile does not expose. See the matching remark on WriteFloat(float).

Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal or a recognized special-value string.

ReadInt()

Reads and consumes a 32-bit signed integer value from the input stream. The value is parsed from an integer token and cast to int.

Declaration
public int ReadInt()
Returns
Type Description
int

The integer value in the range [-2147483648, 2147483647].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadLong()

Reads and consumes a 64-bit signed integer value from the input stream. This is the canonical integer read used internally by smaller integer read methods.

Declaration
public long ReadLong()
Returns
Type Description
long

The long value in the range [-9223372036854775808, 9223372036854775807].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadNull()

Reads and consumes a null literal from the input stream, advancing the read cursor past it. Call this when PeekToken() returns Null, or call it speculatively to test whether the next value is null before reading a typed value.

Declaration
public bool ReadNull()
Returns
Type Description
bool

true if a null literal was present and was consumed; false if the next token is not a null literal, in which case the read cursor is not advanced.

ReadNumberLexeme()

Reads and consumes a numeric literal, returning its exact source text rather than a parsed value.

Declaration
public string ReadNumberLexeme()
Returns
Type Description
string

The numeric literal exactly as it appeared in the input.
Remarks

Parsing a number and re-rendering it does not always reproduce the original text: 1.0 parsed as a double and written back with a round-trip format specifier becomes 1. Callers that must reproduce a document byte-for-byte therefore need the untouched lexeme, which they can emit again through WriteRawValue(string).

The returned text is whatever the source contained, including any leading minus sign, decimal point and exponent. It is not validated or normalized. Use one of the typed read methods when the numeric value itself is what is wanted.

Exceptions
Type Condition
NotSupportedException

Always thrown. A binary stream stores typed values, not textual lexemes; use a typed Read* method instead.

ReadPropertyName()

Reads the next property name key within the current object, consuming it and the associated key-value separator (e.g., the : colon in JSON). Leading commas between properties are consumed automatically by this method.

Declaration
public string ReadPropertyName()
Returns
Type Description
string

The property name string, or null if the reader has reached the closing delimiter of the current object (i.e., no more properties exist).
Exceptions
Type Condition
SerializationException

Thrown if a property name is found but is not followed by the expected key-value separator.

ReadSByte()

Reads and consumes a signed 8-bit integer value from the input stream. The value is parsed from an integer token and cast to sbyte.

Declaration
public sbyte ReadSByte()
Returns
Type Description
sbyte

The signed byte value in the range [-128, 127].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadShort()

Reads and consumes a 16-bit signed integer value from the input stream. The value is parsed from an integer token and cast to short.

Declaration
public short ReadShort()
Returns
Type Description
short

The short value in the range [-32768, 32767].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadStartArray()

Reads and consumes the opening delimiter of an array structure, advancing the read cursor past it. In JSON this is the [ character. Call this before reading any elements of an array, paired with a subsequent call to ReadEndArray().

Declaration
public void ReadStartArray()
Exceptions
Type Condition
SerializationException

Thrown if the next token is not the start of an array structure.

ReadStartObject()

Reads and consumes the opening delimiter of an object structure, advancing the read cursor past it. In JSON this is the { character. Call this before reading any properties of an object, paired with a subsequent call to ReadEndObject().

Declaration
public void ReadStartObject()
Exceptions
Type Condition
SerializationException

Thrown if the next token is not the start of an object structure.

ReadString()

Reads and consumes a string value from the input stream, decoding all escape sequences present in the underlying format (e.g., JSON escape sequences such as ", \, and \uXXXX Unicode escapes).

Declaration
public string ReadString()
Returns
Type Description
string

The decoded string value, or null if the next token is a null literal.
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a string literal and is not a null literal, or if the string contains a malformed escape sequence.

ReadUInt()

Reads and consumes a 32-bit unsigned integer value from the input stream. The value is parsed from an integer token and cast to uint.

Declaration
public uint ReadUInt()
Returns
Type Description
uint

The unsigned integer value in the range [0, 4294967295].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadULong()

Reads and consumes a 64-bit unsigned integer value from the input stream.

Declaration
public ulong ReadULong()
Returns
Type Description
ulong

The unsigned long value in the range [0, 18446744073709551615].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

ReadUShort()

Reads and consumes a 16-bit unsigned integer value from the input stream. The value is parsed from an integer token and cast to ushort.

Declaration
public ushort ReadUShort()
Returns
Type Description
ushort

The unsigned short value in the range [0, 65535].
Exceptions
Type Condition
SerializationException

Thrown if the next token is not a valid numeric literal.

Reset()

Resets the reader to its initial empty state, discarding the current input and returning the cursor to the beginning. Equivalent to calling Reset(string) with an empty string.

Declaration
public void Reset()

Reset(byte[])

Resets the reader with new binary input data. The byte array is decoded to a string (typically as UTF-8) and the cursor is positioned at the start. Passing null is treated as an empty input.

Declaration
public void Reset(byte[] data)
Parameters
Type Name Description
byte[] data

The binary data to read. Implementations are expected to decode this as UTF-8. If null, the reader behaves as though an empty input was provided.

Reset(byte[], int, int)

Reads a window of a larger buffer, without copying it out first.

Declaration
public void Reset(byte[] data, int offset, int count)
Parameters
Type Name Description
byte[] data

The buffer holding the window.
int offset

Where the window starts.
int count

How many bytes the window covers.
Remarks

A caller holding one big buffer with several payloads packed into it would otherwise have to copy each payload into an array of its own before reading it. Reading in place avoids an allocation and a copy per payload, which is what the save container does for every partition it loads.

The window is the whole of the input as far as the reader is concerned: reading past its end raises the same end-of-input error as reading past the end of a buffer.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when the window falls outside the buffer.

Reset(string)

Resets the reader with new string input data, positioning the cursor at the start of the provided string. The reader is ready to begin reading immediately after this call. Passing null is treated as an empty string.

Declaration
public void Reset(string data)
Parameters
Type Name Description
string data

The string data to read. If null, the reader behaves as though an empty string was provided and HasMore will return false.
Remarks

Interprets data as the Base64 encoding produced by GetStringOutput(), which is the only source of string-form binary input in the framework.

Skip()

Skips over the current value at the read position, including all nested content if the value is an object or array. After this call the cursor is positioned immediately after the skipped value (and after any trailing comma separator if one is present). This is useful for ignoring unknown properties during forward- compatible deserialization.

Declaration
public void Skip()

Implements

Extension Methods

See Also