Interface ICustomCodec

Namespace

CStructSharp.Codecs

Assembly

CStructSharp.dll

A caller-supplied primitive type: a name usable in layouts like any built-in primitive, and the span-based read/write rule for one value. Register instances through Codecs. A custom type may be an array element or a pointer target, and is neither bitfield storage nor an enum backing type.

public interface ICustomCodec

Remarks

Read(ReadOnlySpan<byte>, out object?, out int) receives the bytes from the value's start: the whole remaining input for memory input and MemoryStreams, or a window for other streams that grows while the codec answers NeedMoreData. It reports how many bytes the value took; the library charges them to the read budget and advances past them (past the declared size of a fixed-size codec, see FixedSize). Write(Span<byte>, object, out int) receives a destination window and reports the bytes it wrote, or DestinationTooSmall to be offered a larger one (a stream destination grows its scratch window; caller-owned memory cannot and the write fails). Either method may answer InvalidData - or throw - for a value it cannot decode or encode; both surface as the operation's read or write error at the field. Cancellation propagates as OperationCanceledException rather than becoming invalid data.

Implementations must be thread-safe and are compared by reference, so keep one instance per codec: the codec set is part of GetOrCompile(string, byte, bool, bool, CStructCompilationOptions?)'s cache key.

Properties

Alignment

Gets the alignment used by aligned placement; 1 for no alignment requirement.

int Alignment { get; }

Property Value

int

FixedSize

Gets the encoded size in bytes when every value has the same size; null for a variable-length encoding.

int? FixedSize { get; }

Property Value

int?

Remarks

A fixed size is a promise every operation relies on: the layout compiles the offsets after the value from it, and each value occupies exactly this many bytes. A read continues after the declared size even when Read(ReadOnlySpan<byte>, out object?, out int) reports fewer bytes consumed, and an input that ends before it is a short read; a write pads a shorter encoding with zero bytes. A codec that reports more bytes consumed, or asks for more room, than its fixed size fails. Return null for an encoding whose length varies.

Name

Gets the type name accepted in layouts; it must be an identifier and not a built-in codec name.

string Name { get; }

Property Value

string

Methods

Read(ReadOnlySpan<byte>, out object?, out int)

Decodes one value from the start of source.

OperationStatus Read(ReadOnlySpan<byte> source, out object? value, out int bytesConsumed)

Parameters

source ReadOnlySpan<byte>

The bytes from the value's start; for a fixed-size codec at least FixedSize bytes when the input has them.

value object

The decoded value, as the layout publishes it; null unless the status is Done.

bytesConsumed int

The encoded length of the value when the status is Done.

Returns

OperationStatus

Done, NeedMoreData when the value continues past source, or InvalidData.

Write(Span<byte>, object, out int)

Encodes one value at the start of destination.

OperationStatus Write(Span<byte> destination, object value, out int bytesWritten)

Parameters

destination Span<byte>

The window to write into; the library offers a larger one after DestinationTooSmall when the destination can grow.

value object

The caller-supplied value to encode.

bytesWritten int

The encoded length when the status is Done.

Returns

OperationStatus

Done, DestinationTooSmall, or InvalidData for a value the codec cannot encode.