Interface IEncoder

Namespace

ShapeShift

Assembly

ShapeShift.dll

Writes the ShapeShift data model in one particular wire format.

public interface IEncoder

Remarks

An encoder is the "how" half of a format package: the shared converter layer decides what tokens to write, and the encoder decides how each one appears on the wire. It holds no converter, contract, or policy knowledge.

Implementations are conventionally ref structs so that they may hold spans and cannot escape to the heap or cross an await. They are always passed by ref so that a caller sees the mutations each write makes.

Every write must be balanced: each WriteStartMap(int?) is matched by a WriteEndMap(), each WriteStartVector(int?) by a WriteEndVector(), and inside a map every WritePropertyName(scoped ReadOnlySpan<char>) is followed by exactly one value.

Methods

WriteEndMap()

Writes the end of the innermost open map.

void WriteEndMap()

WriteEndVector()

Writes the end of the innermost open vector.

void WriteEndVector()

WriteNull()

Writes an explicit null.

void WriteNull()

WritePropertyName(scoped ReadOnlySpan<char>)

Writes the name of the map entry whose value comes next.

void WritePropertyName(scoped ReadOnlySpan<char> name)

Parameters

name ReadOnlySpan<char>

The property name.

Remarks

Valid only directly inside a map. Many formats encode a key differently from a string value, so this is a distinct operation rather than a call to WriteValue(scoped ReadOnlySpan<char>).

WriteStartMap(int?)

Writes the beginning of a map.

void WriteStartMap(int? propertyCount)

Parameters

propertyCount int?

The number of entries that will follow, when the caller knows it; otherwise null. A length-prefixed format uses it; a format that writes an explicit end token may ignore it, but must then also ignore it consistently so its decoder never reports a count it did not write.

WriteStartVector(int?)

Writes the beginning of a vector.

void WriteStartVector(int? itemCount)

Parameters

itemCount int?

The number of elements that will follow, when the caller knows it; otherwise null.

WriteValue(bool)

Writes a Boolean.

void WriteValue(bool value)

Parameters

value bool

The value to write.

WriteValue(DateTime)

Writes a date and time.

void WriteValue(DateTime value)

Parameters

value DateTime

The value to write.

Remarks

The representation must preserve whatever the format's decoder promises to read back, including the DateTimeKind if the round trip is to be faithful.

WriteValue(decimal)

Writes an exact decimal number.

void WriteValue(decimal value)

Parameters

value decimal

The value to write.

Remarks

Binary floating point cannot hold a decimal exactly. A format without a native decimal type should carry its text so that both the digits and the scale survive.

WriteValue(double)

Writes a double-precision floating-point number.

void WriteValue(double value)

Parameters

value double

The value to write.

WriteValue(Half)

Writes a half-precision floating-point number.

void WriteValue(Half value)

Parameters

value Half

The value to write.

WriteValue(Int128)

Writes a signed 128-bit integer.

void WriteValue(Int128 value)

Parameters

value Int128

The value to write.

Remarks

Few formats have a native 128-bit type. Choose a documented, interoperable encoding (such as decimal text) rather than one that narrows the value.

WriteValue(long)

Writes a signed 64-bit integer.

void WriteValue(long value)

Parameters

value long

The value to write.

Remarks

A format is free to choose the narrowest representation that holds the value, provided its decoder widens it back losslessly.

WriteValue(BigInteger)

Writes an arbitrarily large integer.

void WriteValue(BigInteger value)

Parameters

value BigInteger

The value to write.

WriteValue(scoped ReadOnlySpan<byte>)

Writes a binary value.

void WriteValue(scoped ReadOnlySpan<byte> value)

Parameters

value ReadOnlySpan<byte>

The bytes to write.

Exceptions

NotSupportedException

Thrown when the format has no binary representation.

WriteValue(scoped ReadOnlySpan<char>)

Writes text without requiring the caller to materialize a string.

void WriteValue(scoped ReadOnlySpan<char> value)

Parameters

value ReadOnlySpan<char>

The text to write.

Remarks

This is the allocation-free path converters prefer; implement it directly rather than by forwarding to WriteValue(string).

WriteValue(float)

Writes a single-precision floating-point number.

void WriteValue(float value)

Parameters

value float

The value to write.

WriteValue(string)

Writes a string.

void WriteValue(string value)

Parameters

value string

The value to write.

WriteValue(TimeSpan)

Writes a duration.

void WriteValue(TimeSpan value)

Parameters

value TimeSpan

The value to write.

WriteValue(UInt128)

Writes an unsigned 128-bit integer.

void WriteValue(UInt128 value)

Parameters

value UInt128

The value to write.

WriteValue(ulong)

Writes an unsigned 64-bit integer.

void WriteValue(ulong value)

Parameters

value ulong

The value to write.