Struct MessagePackReader
- Namespace
- Nerdbank.MessagePack
- Assembly
- Nerdbank.MessagePack.dll
A primitive types reader for the MessagePack format.
public ref struct MessagePackReader- Inherited Members
Remarks
Constructors
MessagePackReader(scoped in ReadOnlySequence<byte>)
Initializes a new instance of the MessagePackReader struct.
public MessagePackReader(scoped in ReadOnlySequence<byte> msgpack)Parameters
msgpackReadOnlySequence<byte>The sequence to read from.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
MessagePackReader(ReadOnlyMemory<byte>)
Initializes a new instance of the MessagePackReader struct.
public MessagePackReader(ReadOnlyMemory<byte> msgpack)Parameters
msgpackReadOnlyMemory<byte>The sequence to read from.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Properties
Consumed
Gets the number of bytes consumed by the reader.
public long Consumed { get; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
End
Gets a value indicating whether the reader is at the end of the sequence.
public bool End { get; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
IsNil
Gets a value indicating whether the reader position is pointing at a nil value.
public bool IsNil { get; }Property Value
Exceptions
- EndOfStreamException
Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.
NextCode
Gets the type of the next MessagePack block.
public byte NextCode { get; }Property Value
Remarks
See MessagePackCode for valid message pack codes and ranges.
Exceptions
- EndOfStreamException
Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.
NextMessagePackType
Gets the next message pack type to be read.
public MessagePackType NextMessagePackType { get; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Position
Gets the current position of the reader within Sequence.
public SequencePosition Position { get; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Sequence
Gets the ReadOnlySequence<T> originally supplied to the constructor.
public ReadOnlySequence<byte> Sequence { get; }Property Value
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
Methods
Clone(scoped in ReadOnlySequence<byte>)
Initializes a new instance of the MessagePackReader struct, with the same settings as this one, but with its own buffer to read from.
public MessagePackReader Clone(scoped in ReadOnlySequence<byte> readOnlySequence)Parameters
readOnlySequenceReadOnlySequence<byte>The sequence to read from.
Returns
- MessagePackReader
The new reader.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
CreatePeekReader()
Creates a new MessagePackReader at this reader's current position. The two readers may then be used independently without impacting each other.
public MessagePackReader CreatePeekReader()Returns
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadArrayHeader()
Read an array header from Array16, Array32, or some built-in code between MinFixArray and MaxFixArray.
public int ReadArrayHeader()Returns
- int
The number of elements in the array.
Exceptions
- EndOfStreamException
Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.
- MessagePackSerializationException
Thrown if a code other than an array header is encountered.
ReadBoolean()
public bool ReadBoolean()Returns
- bool
The value.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadByte()
Reads an byte value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public byte ReadByte()Returns
- byte
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadBytes()
Reads a span of bytes, whose length is determined by a header of one of these types: Bin8, Bin16, Bin32, or to support OldSpec compatibility: Str16, Str32, or something between MinFixStr and MaxFixStr.
public ReadOnlySequence<byte>? ReadBytes()Returns
- ReadOnlySequence<byte>?
A sequence of bytes, or null if the read token is Nil. The data is a slice from the original sequence passed to this reader's constructor.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadChar()
public char ReadChar()Returns
- char
A character.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadDateTime()
Reads a DateTime from a value encoded with FixExt4, FixExt8, or Ext8. Expects extension type code DateTime.
public DateTime ReadDateTime()Returns
- DateTime
The value.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadDateTime(ExtensionHeader)
Reads a DateTime from a value encoded with FixExt4, FixExt8, Ext8. Expects extension type code DateTime.
public DateTime ReadDateTime(ExtensionHeader header)Parameters
headerExtensionHeaderThe extension header that was already read.
Returns
- DateTime
The value.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadDouble()
Reads an double value from any value encoded with: Float64, Float32, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, or some value between MinNegativeFixInt and MaxNegativeFixInt, or some value between MinFixInt and MaxFixInt.
public double ReadDouble()Returns
- double
The value.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadExtension()
Reads an extension format header and data, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.
public Extension ReadExtension()Returns
- Extension
The extension format. The data is a slice from the original sequence passed to this reader's constructor.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadExtensionHeader()
Reads an extension format header, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.
public ExtensionHeader ReadExtensionHeader()Returns
- ExtensionHeader
The extension header.
Remarks
This call should always be followed by a successful call to ReadRaw(long), with the length of bytes specified by Length (even if zero), so that the overall structure can be recorded as read.
Exceptions
- EndOfStreamException
Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the bytes the header claims to be there.
- MessagePackSerializationException
Thrown if a code other than an extension format header is encountered.
ReadInt16()
Reads an short value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public short ReadInt16()Returns
- short
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadInt32()
Reads an int value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public int ReadInt32()Returns
- int
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadInt64()
Reads an long value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public long ReadInt64()Returns
- long
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadMapHeader()
public int ReadMapHeader()Returns
- int
The number of key=value pairs in the map.
Exceptions
- EndOfStreamException
Thrown if the header cannot be read in the bytes left in the Sequence or if it is clear that there are insufficient bytes remaining after the header to include all the elements the header claims to be there.
- MessagePackSerializationException
Thrown if a code other than an map header is encountered.
ReadNil()
Reads a Nil value.
public object? ReadNil()Returns
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadRaw(SerializationContext)
Reads the next MessagePack structure.
public RawMessagePack ReadRaw(SerializationContext context)Parameters
contextSerializationContextThe serialization context. Used for the stack guard.
Returns
- RawMessagePack
The raw MessagePack sequence, taken as a slice from the Sequence. The caller should copy any data that must out-live its underlying buffers using ToOwned().
Remarks
The entire structure is read, including content of maps or arrays, or any other type with payloads.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadRaw(long)
Reads a sequence of bytes without any decoding.
public RawMessagePack ReadRaw(long length)Parameters
lengthlong- The number of bytes to read. This should always be the length of exactly one msgpack structure.
Returns
- RawMessagePack
The raw MessagePack sequence, taken as a slice from the Sequence. The caller should copy any data that must out-live its underlying buffers using ToOwned().
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadSByte()
Reads an sbyte value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public sbyte ReadSByte()Returns
- sbyte
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadSingle()
Reads an float value from any value encoded with: Float32, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, or some value between MinNegativeFixInt and MaxNegativeFixInt, or some value between MinFixInt and MaxFixInt.
public float ReadSingle()Returns
- float
The value.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadString()
Reads a string, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.
public string? ReadString()Returns
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadStringSequence()
Reads a string of bytes, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.
public ReadOnlySequence<byte>? ReadStringSequence()Returns
- ReadOnlySequence<byte>?
The sequence of bytes, or null if the read token is Nil. The data is a slice from the original sequence passed to this reader's constructor.
Remarks
This method never allocates memory.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
ReadStringSpan()
Reads a string of bytes, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.
public ReadOnlySpan<byte> ReadStringSpan()Returns
- ReadOnlySpan<byte>
The UTF-8 bytes of the string.
Remarks
This method may allocate memory if the string is not contiguous in memory. Use TryReadStringSpan(out ReadOnlySpan<byte>) to avoid allocating memory while reading strings that are contiguous or to avoid throwing when the value is null.
Exceptions
- EndOfStreamException
If the buffer does not contain enough bytes to read the next msgpack token.
- MessagePackSerializationException
Thrown if NextCode is not a string.
ReadUInt16()
Reads an ushort value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public ushort ReadUInt16()Returns
- ushort
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadUInt32()
Reads an uint value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public uint ReadUInt32()Returns
- uint
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
ReadUInt64()
Reads an ulong value from: Some value between MinNegativeFixInt and MaxNegativeFixInt, Some value between MinFixInt and MaxFixInt, or any of the other MsgPack integer types.
public ulong ReadUInt64()Returns
- ulong
The value.
Exceptions
- OverflowException
Thrown when the value exceeds what can be stored in the returned type.
Skip(SerializationContext)
Advances the reader to the next MessagePack structure to be read.
public void Skip(SerializationContext context)Parameters
contextSerializationContextSerialization context. Used for the stack guard.
Remarks
The entire structure is skipped, including content of maps or arrays, or any other type with payloads. To get the raw MessagePack sequence that was skipped, use ReadRaw(SerializationContext) instead.
Exceptions
- MessagePackSerializationException
Thrown when reading methods fail due to invalid data.
- EndOfStreamException
Thrown by reading methods when there are not enough bytes to read the required value.
TryReadArrayHeader(out int)
Reads an array header from Array16, Array32, or some built-in code between MinFixArray and MaxFixArray if there is sufficient buffer to read it.
public bool TryReadArrayHeader(out int count)Parameters
countintReceives the number of elements in the array if the entire array header could be read.
Returns
- bool
true if there was sufficient buffer and an array header was found; false if the buffer incompletely describes an array header.
Exceptions
- MessagePackSerializationException
Thrown if a code other than an array header is encountered.
TryReadExtensionHeader(out ExtensionHeader)
Reads an extension format header, based on one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32 if there is sufficient buffer to read it.
public bool TryReadExtensionHeader(out ExtensionHeader extensionHeader)Parameters
extensionHeaderExtensionHeaderReceives the extension header if the remaining bytes in the Sequence fully describe the header.
Returns
- bool
A value indicating whether an extension header is fully represented at the reader's position.
Remarks
This call should always be followed by a successful call to ReadRaw(long), with the length of bytes specified by Length (even if zero), so that the overall structure can be recorded as read.
Exceptions
- MessagePackSerializationException
Thrown if a code other than an extension format header is encountered.
TryReadMapHeader(out int)
Reads a map header from Map16, Map32, or some built-in code between MinFixMap and MaxFixMap if there is sufficient buffer to read it.
public bool TryReadMapHeader(out int count)Parameters
countintReceives the number of key=value pairs in the map if the entire map header can be read.
Returns
- bool
true if there was sufficient buffer and a map header was found; false if the buffer incompletely describes an map header.
Exceptions
- MessagePackSerializationException
Thrown if a code other than an map header is encountered.
TryReadNil()
Reads nil if it is the next token.
public bool TryReadNil()Returns
Exceptions
- EndOfStreamException
Thrown if the end of the sequence provided to the constructor is reached before the expected end of the data.
TryReadStringSpan(out ReadOnlySpan<byte>)
Reads a string of bytes, whose length is determined by a header of one of these types: Str8, Str16, Str32, or a code between MinFixStr and MaxFixStr.
public bool TryReadStringSpan(out ReadOnlySpan<byte> span)Parameters
spanReadOnlySpan<byte>Receives the span to the string.
Returns
- bool
true if the string is contiguous in memory such that it could be set as a single span. false if the read token is Nil or the string is not in a contiguous span.
Remarks
Callers should generally be prepared for a false result and failover to calling ReadStringSequence() which can represent a null result and handle strings that are not contiguous in memory.
Exceptions
- EndOfStreamException
If the buffer does not contain enough bytes to read the next msgpack token.
- MessagePackSerializationException
Thrown if NextCode is neither a string nor a nil.