Interface IDecoder
- Namespace
- ShapeShift
- Assembly
- ShapeShift.dll
Reads the ShapeShift data model from one particular wire format.
public interface IDecoderRemarks
A decoder is a pull parser. Two rules make up the whole contract the format-neutral converter layer relies on:
- NextTokenType is a peek: it reports what comes next without consuming anything, and may be called any number of times with the same answer.
-
Every
Readmethod consumes exactly one token -- or, for containers, exactly one start or end token -- and leaves the decoder positioned on the next one. A method that fails to produce a value may leave the decoder unusable, but must fail by throwing DecoderException.
Implementations are conventionally ref structs and are always passed by ref, so that the position advanced by a nested read is seen by the caller.
A decoder reads attacker-controlled bytes. Every length or count it reads from the input must be validated against the input actually available before it is used to slice, allocate, or loop.
Properties
NextTokenType
Gets the type of the next token without consuming it.
TokenType NextTokenType { get; }Property Value
- TokenType
The token that the next
Readcall would consume, or EndDocument once the input has been fully consumed.
Exceptions
- DecoderException
Thrown when the next bytes are not a recognizable token.
Methods
ReadBigInteger()
Consumes an arbitrarily large integer.
BigInteger ReadBigInteger()Returns
- BigInteger
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer.
ReadBoolean()
Consumes a Boolean.
bool ReadBoolean()Returns
- bool
The value.
Exceptions
- DecoderException
Thrown when the next token is not a Boolean.
ReadByteArray()
Reads a binary value.
byte[] ReadByteArray()Returns
- byte[]
The decoded bytes.
Exceptions
- NotSupportedException
Thrown when the format has no binary representation.
ReadCharSpan()
Consumes text without necessarily allocating a string.
ReadOnlySpan<char> ReadCharSpan()Returns
- ReadOnlySpan<char>
The text. The span is valid only until the next read.
Exceptions
- DecoderException
Thrown when the next token is not a string.
ReadDateTime()
Consumes a date and time.
DateTime ReadDateTime()Returns
- DateTime
The value.
Exceptions
- DecoderException
Thrown when the next token is not one this format writes dates as.
ReadDecimal()
Consumes an exact decimal number.
decimal ReadDecimal()Returns
- decimal
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number a decimal can hold.
ReadDouble()
Consumes a double-precision floating-point number.
double ReadDouble()Returns
- double
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number.
ReadDynamicNumber()
Reads a number while preserving the representation available from the format.
ShapeShiftNumber ReadDynamicNumber()Returns
- ShapeShiftNumber
The dynamic number.
Remarks
This is what ShapeShiftValue and unknown-property retention use, so a value that arrived as a wide or unsigned integer can be written back the way it came. The default implementation narrows everything to decimal; override it to keep the width the payload actually used.
ReadEndMap()
Consumes the end of the innermost open map.
void ReadEndMap()Remarks
A format whose maps are length-prefixed has no end token on the wire and synthesizes one, so callers may always read the end token they saw reported by NextTokenType.
Exceptions
- DecoderException
Thrown when the map is not positioned at its end.
ReadEndVector()
Consumes the end of the innermost open vector.
void ReadEndVector()Exceptions
- DecoderException
Thrown when the vector is not positioned at its end.
ReadHalf()
Consumes a half-precision floating-point number.
Half ReadHalf()Returns
- Half
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number.
ReadInt128()
Consumes a signed 128-bit integer.
Int128 ReadInt128()Returns
- Int128
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer this width can hold.
ReadInt64()
Consumes a signed 64-bit integer.
long ReadInt64()Returns
- long
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer this width can hold.
ReadNull()
Consumes a null.
void ReadNull()Remarks
The default implementation defers to TryReadNull(), which consumes the token, and throws when it reports false. A decoder overrides it only to produce a more precise error message.
Exceptions
- DecoderException
Thrown when the next token is not Null.
ReadPropertyName()
Consumes the name of the map entry whose value comes next.
ReadOnlySpan<char> ReadPropertyName()Returns
- ReadOnlySpan<char>
The property name. The span is valid only until the next read.
Exceptions
- DecoderException
Thrown when the decoder is not positioned at a map key.
ReadSingle()
Consumes a single-precision floating-point number.
float ReadSingle()Returns
- float
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number.
ReadStartMap()
Consumes the beginning of a map.
int? ReadStartMap()Returns
- int?
The number of entries the map declares, or null when the format does not declare one. A count, once reported, must be correct.
Exceptions
- DecoderException
Thrown when the next token is not StartMap.
ReadStartVector()
Consumes the beginning of a vector.
int? ReadStartVector()Returns
- int?
The number of elements the vector declares, or null when the format does not declare one. A count, once reported, must be correct.
Exceptions
- DecoderException
Thrown when the next token is not StartVector.
ReadString()
Consumes a string.
string ReadString()Returns
- string
The value.
Exceptions
- DecoderException
Thrown when the next token is not a string.
ReadTimeSpan()
Consumes a duration.
TimeSpan ReadTimeSpan()Returns
- TimeSpan
The value.
Exceptions
- DecoderException
Thrown when the next token is not one this format writes durations as.
ReadUInt128()
Consumes an unsigned 128-bit integer.
UInt128 ReadUInt128()Returns
- UInt128
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer this width can hold.
ReadUInt64()
Consumes an unsigned 64-bit integer.
ulong ReadUInt64()Returns
- ulong
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer this width can hold.
Skip()
Consumes the next value in its entirety, however deeply nested, without converting it.
void Skip()Remarks
Unknown-property retention, positional contracts, and ShapeShiftPath traversal all build on this, so it is worth implementing in terms of declared widths rather than by decoding each value. A skip walks attacker-controlled structure, so bound its nesting.
Exceptions
- DecoderException
Thrown when there is no value to skip, or the value is malformed.
TryReadNull()
Consumes the next token if -- and only if -- it is a null.
bool TryReadNull()Returns
- bool
true when the next token was Null and has now been consumed; false when it was anything else, in which case nothing was consumed and the decoder is left exactly where it was.
Remarks
These are the conventional Try semantics: this is ReadNull() without the throw.
A true answer means the null is gone, so the caller must not follow it with
ReadNull().
A converter that needs to know whether a null is coming without consuming it -- because it intends to hand the token to another converter -- asks NextTokenType instead, which is the peek.
Exceptions
- DecoderException
Thrown when the next bytes are not a recognizable token.