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

CancellationToken

Gets or sets the cancellation token for this serialization operation.

public CancellationToken CancellationToken { readonly get; set; }

Property Value

CancellationToken

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

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

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

Parameters

dateTime DateTime

The value to write.

Exceptions

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

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

public void Write(ReadOnlySpan<byte> src)

Parameters

src ReadOnlySpan<byte>

The span of bytes to write.

Remarks

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

Write(ReadOnlySpan<char>)

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

public void Write(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 a raw 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(ReadOnlySpan<byte>) after calling this method to actually write the content. Alternatively a single call to Write(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 bytes directly into the message pack writer.

public void WriteRaw(in ReadOnlySequence<byte> rawMessagePackBlock)

Parameters

rawMessagePackBlock ReadOnlySequence<byte>

The span of bytes to copy from.

WriteRaw(ReadOnlySpan<byte>)

Copies bytes directly into the message pack writer.

public void WriteRaw(ReadOnlySpan<byte> rawMessagePackBlock)

Parameters

rawMessagePackBlock ReadOnlySpan<byte>

The span of bytes to copy from.

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(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(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(ReadOnlySpan<byte>) after calling this method to actually write the content. Alternatively a single call to WriteString(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.