Struct MessagePackWriter

Namespace

Nerdbank.MessagePack

Assembly

Nerdbank.MessagePack.dll

A primitive types writer for the MessagePack format.

public ref struct MessagePackWriter

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

The MessagePack spec..

Constructors

MessagePackWriter(IBufferWriter<byte>)

Initializes a new instance of the MessagePackWriter struct.

public MessagePackWriter(IBufferWriter<byte> writer)

Parameters

writer IBufferWriter<byte>

The writer to use.

Properties

OldSpec

Gets or sets a value indicating whether to write in old spec compatibility mode.

public bool OldSpec { readonly get; set; }

Property Value

bool

UnflushedBytes

Gets the number of bytes that have been written but not yet committed flushed to the underlying IBufferWriter<T>.

public int UnflushedBytes { get; }

Property Value

int

Methods

Advance(int)

Commits memory previously returned from GetSpan(int) as initialized.

public void Advance(int length)

Parameters

length int

The number of bytes initialized with messagepack data from the previously returned span.

See Also

Advance(int)

Clone(IBufferWriter<byte>)

Initializes a new instance of the MessagePackWriter struct, with the same settings as this one, but with its own buffer writer.

public MessagePackWriter Clone(IBufferWriter<byte> writer)

Parameters

writer IBufferWriter<byte>

The writer to use for the new instance.

Returns

MessagePackWriter

The new writer.

Flush()

Ensures everything previously written has been flushed to the underlying IBufferWriter<T>.

public void Flush()

GetEncodedLength(long)

Get the number of bytes required to encode a value in msgpack.

public static int GetEncodedLength(long value)

Parameters

value long

The value to encode.

Returns

int

The byte length; One of 1, 2, 3, 5 or 9 bytes.

GetEncodedLength(ulong)

Get the number of bytes required to encode a value in msgpack.

public static int GetEncodedLength(ulong value)

Parameters

value ulong

The value to encode.

Returns

int

The byte length; One of 1, 2, 3, 5 or 9 bytes.

GetSpan(int)

Gets memory where raw messagepack data can be written.

public Span<byte> GetSpan(int length)

Parameters

length int

The minimum length of the returned Span<T>. If 0, a non-empty buffer is returned.

Returns

Span<byte>

The span of memory to write to. This may exceed length.

Remarks

After initializing the resulting memory, always follow up with a call to Advance(int).

This is similar in purpose to WriteRaw(scoped ReadOnlySpan<byte>) but provides uninitialized memory for the caller to write to instead of copying initialized memory from elsewhere.

See Also

GetSpan(int)

Write(Extension)

Writes an extension format, using the smallest one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.

public void Write(Extension extensionData)

Parameters

extensionData Extension

The extension data.

Write(ExtensionHeader)

Writes the extension format header, using the smallest one of these codes: FixExt1, FixExt2, FixExt4, FixExt8, FixExt16, Ext8, Ext16, or Ext32.

public void Write(ExtensionHeader extensionHeader)

Parameters

extensionHeader ExtensionHeader

The extension header.

Write(MessagePackString)

Writes a pre-encoded msgpack string.

public void Write(MessagePackString value)

Parameters

value MessagePackString

The string to write.

Write(RawMessagePack)

Copies bytes directly into the message pack writer.

public void Write(RawMessagePack msgpack)

Parameters

msgpack RawMessagePack

The bytes to copy directly to the output buffer.

Write(bool)

Writes a bool value using either True or False.

public void Write(bool value)

Parameters

value bool

The value.

Write(in ReadOnlySequence<byte>)

Writes an arbitrary sequence of bytes, prefixed with a length encoded as the smallest fitting from: Bin8, Bin16, or Bin32.

public void Write(in ReadOnlySequence<byte> src)

Parameters

src ReadOnlySequence<byte>

The span of bytes to write.

Remarks

Use ReadBytes() to read the bytes back.

When OldSpec is true, the msgpack code used is Str8, Str16 or Str32 instead.

Write(byte)

Writes a byte value using a 1-byte code when possible, otherwise as UInt8.

public void Write(byte value)

Parameters

value byte

The value.

Write(byte[]?)

Writes an arbitrary byte[], prefixed with a length encoded as the smallest fitting from: Bin8, Bin16, Bin32, or Nil if src is null.

public void Write(byte[]? src)

Parameters

src byte[]

The array of bytes to write. May be null.

Remarks

Use ReadBytes() to read the bytes back.

Write(char)

Writes a char value using a 1-byte code when possible, otherwise as UInt8 or UInt16.

public void Write(char value)

Parameters

value char

The value.

Write(DateTime)

Writes a DateTime using the message code DateTime.

public void Write(DateTime value)

Parameters

value DateTime

The value to write. This must not have Kind set to Unspecified.

Exceptions

ArgumentException

Thrown if value has a Kind set to Unspecified.

NotSupportedException

Thrown when OldSpec is true because the old spec does not define a DateTime format.

Write(double)

Writes a Float64 value.

public void Write(double value)

Parameters

value double

The value.

Write(short)

Writes a short using a built-in 1-byte code when within specific MessagePack-supported ranges, or the most compact of UInt8, UInt16, Int8, or Int16.

public void Write(short value)

Parameters

value short

The value to write.

Write(int)

Writes an int using a built-in 1-byte code when within specific MessagePack-supported ranges, or the most compact of UInt8, UInt16, UInt32, Int8, Int16, Int32.

public void Write(int value)

Parameters

value int

The value to write.

Write(long)

Writes an long using a built-in 1-byte code when within specific MessagePack-supported ranges, or the most compact of UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64.

public void Write(long value)

Parameters

value long

The value to write.

Write(scoped ReadOnlySpan<byte>)

Writes an arbitrary span of bytes, prefixed with a length encoded as the smallest fitting from: Bin8, Bin16, or Bin32.

public void Write(scoped ReadOnlySpan<byte> src)

Parameters

src ReadOnlySpan<byte>

The span of bytes to write.

Remarks

Use ReadBytes() to read the bytes back.

When OldSpec is true, the msgpack code used is Str8, Str16 or Str32 instead.

Write(scoped ReadOnlySpan<char>)

Writes out a string, prefixed with the length using one of these message codes: MinFixStr, Str8, Str16, Str32.

public void Write(scoped ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The value to write.

Write(sbyte)

Writes an 8-bit value using a 1-byte code when possible, otherwise as Int8.

public void Write(sbyte value)

Parameters

value sbyte

The value.

Write(float)

Writes a Float32 value.

public void Write(float value)

Parameters

value float

The value.

Write(string?)

Writes out a string, prefixed with the length using one of these message codes: MinFixStr, Str8, Str16, Str32, or Nil if the value is null.

public void Write(string? value)

Parameters

value string

The value to write. May be null.

Write(ushort)

Writes a ushort value using a 1-byte code when possible, otherwise as UInt8 or UInt16.

public void Write(ushort value)

Parameters

value ushort

The value.

Write(uint)

Writes an uint using a built-in 1-byte code when within specific MessagePack-supported ranges, or the most compact of UInt8, UInt16, or UInt32.

public void Write(uint value)

Parameters

value uint

The value to write.

Write(ulong)

Writes an ulong using a built-in 1-byte code when within specific MessagePack-supported ranges, or the most compact of UInt8, UInt16, UInt32, Int8, Int16, Int32.

public void Write(ulong value)

Parameters

value ulong

The value to write.

WriteArrayHeader(int)

Write the length of the next array to be written in the most compact form of MinFixArray, Array16, or Array32.

public void WriteArrayHeader(int count)

Parameters

count int

The number of elements that will be written in the array.

WriteArrayHeader(uint)

Write the length of the next array to be written in the most compact form of MinFixArray, Array16, or Array32.

public void WriteArrayHeader(uint count)

Parameters

count uint

The number of elements that will be written in the array.

WriteBinHeader(int)

Writes the header that precedes an arbitrary binary sequence with a length encoded as the smallest fitting from: Bin8, Bin16, or Bin32.

public void WriteBinHeader(int length)

Parameters

length int

The length of bytes that will be written next.

Remarks

The caller should use WriteRaw(in ReadOnlySequence<byte>) or WriteRaw(scoped ReadOnlySpan<byte>) after calling this method to actually write the content. Alternatively a single call to Write(scoped ReadOnlySpan<byte>) or Write(in ReadOnlySequence<byte>) will take care of the header and content in one call.

When OldSpec is true, the msgpack code used is Str8, Str16 or Str32 instead.

WriteInt16(short)

Writes a short using Int16.

public void WriteInt16(short value)

Parameters

value short

The value to write.

WriteInt32(int)

Writes an int using Int32.

public void WriteInt32(int value)

Parameters

value int

The value to write.

WriteInt64(long)

Writes a long using Int64.

public void WriteInt64(long value)

Parameters

value long

The value to write.

WriteInt8(sbyte)

Writes an 8-bit value using Int8.

public void WriteInt8(sbyte value)

Parameters

value sbyte

The value.

WriteMapHeader(int)

Write the length of the next map to be written in the most compact form of MinFixMap, Map16, or Map32.

public void WriteMapHeader(int count)

Parameters

count int

The number of key=value pairs that will be written in the map.

WriteMapHeader(uint)

Write the length of the next map to be written in the most compact form of MinFixMap, Map16, or Map32.

public void WriteMapHeader(uint count)

Parameters

count uint

The number of key=value pairs that will be written in the map.

WriteNil()

Writes a Nil value.

public void WriteNil()

WriteRaw(in ReadOnlySequence<byte>)

Copies msgpack bytes directly into the message pack writer.

public void WriteRaw(in ReadOnlySequence<byte> rawMessagePackBlock)

Parameters

rawMessagePackBlock ReadOnlySequence<byte>

The bytes to copy directly to the output buffer.

Remarks

This method is for copy valid msgpack structures directly to the output buffer. Arbitrary binary blobs may only be written using this method directly following a call to WriteBinHeader(int). Otherwise use Write(scoped ReadOnlySpan<byte>) to write arbitrary binary blobs.

WriteRaw(scoped ReadOnlySpan<byte>)

Copies msgpack bytes directly into the message pack writer.

public void WriteRaw(scoped ReadOnlySpan<byte> rawMessagePackBlock)

Parameters

rawMessagePackBlock ReadOnlySpan<byte>

The bytes to copy directly to the output buffer.

Remarks

This method is for copy valid msgpack structures directly to the output buffer. Arbitrary binary blobs may only be written using this method directly following a call to WriteBinHeader(int). Otherwise use Write(scoped ReadOnlySpan<byte>) to write arbitrary binary blobs.

WriteString(in ReadOnlySequence<byte>)

Writes out an array of bytes that (may) represent a UTF-8 encoded string, prefixed with the length using one of these message codes: MinFixStr, Str8, Str16, or Str32.

public void WriteString(in ReadOnlySequence<byte> utf8stringBytes)

Parameters

utf8stringBytes ReadOnlySequence<byte>

The bytes to write.

WriteString(scoped ReadOnlySpan<byte>)

Writes out an array of bytes that (may) represent a UTF-8 encoded string, prefixed with the length using one of these message codes: MinFixStr, Str8, Str16, or Str32.

public void WriteString(scoped ReadOnlySpan<byte> utf8stringBytes)

Parameters

utf8stringBytes ReadOnlySpan<byte>

The bytes to write.

WriteStringHeader(int)

Writes out the header that may precede a UTF-8 encoded string, prefixed with the length using one of these message codes: MinFixStr, Str8, Str16, or Str32.

public void WriteStringHeader(int byteCount)

Parameters

byteCount int

The number of bytes in the string that will follow this header.

Remarks

The caller should use WriteRaw(in ReadOnlySequence<byte>) or WriteRaw(scoped ReadOnlySpan<byte>) after calling this method to actually write the content. Alternatively a single call to WriteString(scoped ReadOnlySpan<byte>) or WriteString(in ReadOnlySequence<byte>) will take care of the header and content in one call.

WriteUInt16(ushort)

Writes a ushort value using UInt16.

public void WriteUInt16(ushort value)

Parameters

value ushort

The value.

WriteUInt32(uint)

Writes an uint using UInt32.

public void WriteUInt32(uint value)

Parameters

value uint

The value to write.

WriteUInt64(ulong)

Writes an ulong using Int32.

public void WriteUInt64(ulong value)

Parameters

value ulong

The value to write.

WriteUInt8(byte)

Writes a byte value using UInt8.

public void WriteUInt8(byte value)

Parameters

value byte

The value.