Struct CborDecoder
- Namespace
- ShapeShift.Cbor
- Assembly
- ShapeShift.Cbor.dll
Reads ShapeShift tokens from a CBOR document.
public ref struct CborDecoder : IDecoder- Implements
- Inherited Members
Constructors
CborDecoder(ReadOnlyMemory<byte>)
Initializes a new instance of the CborDecoder struct.
public CborDecoder(ReadOnlyMemory<byte> cbor)Parameters
cborReadOnlyMemory<byte>The encoded CBOR document.
Properties
BytesRemaining
Gets the number of unread bytes remaining in the document.
public int BytesRemaining { get; }Property Value
NextTokenType
Gets the type of the next token without consuming it.
public 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.
Reader
Gets the underlying CBOR reader for advanced custom converters.
public CborReader Reader { get; }Property Value
Methods
EnsureEndOfDocument()
Ensures no trailing CBOR data remains.
public void EnsureEndOfDocument()Exceptions
- DecoderException
Thrown when trailing CBOR data remains.
ReadBigInteger()
Consumes an arbitrarily large integer.
public BigInteger ReadBigInteger()Returns
- BigInteger
The value.
Exceptions
- DecoderException
Thrown when the next token is not an integer.
ReadBoolean()
Consumes a Boolean.
public bool ReadBoolean()Returns
- bool
The value.
Exceptions
- DecoderException
Thrown when the next token is not a Boolean.
ReadByteArray()
Reads a binary value.
public 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.
public 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.
public 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.
public 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.
public 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.
public 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.
public 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.
public void ReadEndVector()Exceptions
- DecoderException
Thrown when the vector is not positioned at its end.
ReadHalf()
Consumes a half-precision floating-point number.
public Half ReadHalf()Returns
- Half
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number.
ReadInt128()
Consumes a signed 128-bit integer.
public 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.
public 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.
public 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.
public 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.
public float ReadSingle()Returns
- float
The value.
Exceptions
- DecoderException
Thrown when the next token is not a number.
ReadStartMap()
Consumes the beginning of a map.
public 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.
public 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.
public string ReadString()Returns
- string
The value.
Exceptions
- DecoderException
Thrown when the next token is not a string.
ReadTimeSpan()
Consumes a duration.
public 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.
public 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.
public 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.
public 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.
public 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.