Class ScyllaJSONReader

JSON format implementation of IScyllaReader that parses a JSON string in a forward-only, token-by-token fashion without allocating intermediate DOM nodes. Provides structured access to all JSON value types, object properties, and arrays.

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

The reader maintains a single integer cursor (_position) that advances through the raw JSON character array as tokens are consumed. Whitespace and value separators (commas) are skipped automatically by internal helpers, so callers do not need to account for JSON formatting differences.

Special float/double values: Because the JSON specification does not support IEEE 754 special values (NaN, Infinity), this reader recognizes the string-encoded sentinels "NaN", "Infinity", and "-Infinity" as produced by ScyllaJSONWriter and converts them to the corresponding float or double constants.

String encoding: All standard JSON escape sequences (\", \\, \/, \b, \f, \n, \r, \t, and \uXXXX Unicode escapes) are decoded during ReadString().

Byte arrays: Byte arrays are stored as Base64-encoded strings in JSON and are decoded back to byte[] by ReadBytes().

Reader instances are pooled by ScyllaSerialization. Prefer calling FromJSON<T>(string) rather than constructing readers directly in hot paths.

Constructors

ScyllaJSONReader()

Initializes a new ScyllaJSONReader with no input data. Call Reset(string) or SetInput(string) before reading.

Declaration
public ScyllaJSONReader()

ScyllaJSONReader(string)

Initializes a new ScyllaJSONReader and sets the specified JSON string as the initial input. The reader is ready to begin reading immediately.

Declaration
public ScyllaJSONReader(string json)
Parameters
Type Name Description
string json

The JSON string to parse. Passing null is treated as an empty string, leaving the reader with no tokens to read.

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

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

SetInput(string)

Sets the JSON string to read from and resets the cursor to the beginning. This is a convenience alias for Reset(string) used by ScyllaSerialization when retrieving a pooled reader instance.

Declaration
public void SetInput(string json)
Parameters
Type Name Description
string json

The JSON string to parse. Passing null is treated as an empty string.

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

SkipComma()

Advances the read cursor past a comma separator and any surrounding whitespace, if a comma is present at the current position after skipping whitespace. This is used externally to advance past element separators in contexts where the normal read methods do not automatically consume them (e.g., between array elements when iterating manually).

Declaration
public void SkipComma()

Implements

Extension Methods

See Also