Interface IScyllaReader

Low-level, format-agnostic interface for reading serialized data in a forward-only, token-by-token fashion. Implementations decode a specific wire format (such as JSON) and expose its content through a uniform API that the serialization engine can consume without knowing the underlying representation.

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

Readers are stateful and advance a read cursor through the input with every call to a Read* method. The general usage pattern is:

  1. Call PeekToken() to inspect the next token without consuming it, then dispatch to the appropriate read method.
  2. For objects, call ReadStartObject(), loop over ReadPropertyName() until it returns null, reading each value, then call ReadEndObject().
  3. For arrays, call ReadStartArray(), loop while PeekToken() is not EndArray, reading each element, then call ReadEndArray().
  4. Call Reset(string) or Reset(byte[]) to reuse the same reader instance with new input data.

Readers are typically obtained from an object pool managed by ScyllaSerialization and should not be created directly in hot paths.

Implementations must throw SerializationException when the input is malformed or a read method is called for a token type that does not match the current token.

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

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

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

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

Extension Methods

See Also