Class CStruct

Namespace: CStructSharp

Assembly: CStructSharp.dll

Compiles a C-like layout definition and uses it to read, inspect, write, or update binary data. Create one instance per layout, then reuse it for sequential or concurrent operations. Concurrent calls must use distinct streams, payload graphs, and other mutable resources, or the caller must synchronize each shared resource for the complete operation.

public sealed class CStruct

Inheritance: object

CStruct

Inherited Members: object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Examples

Create one CStruct, reuse it for dynamic and typed reads, and use TryReadValue when a short input is an expected failure rather than an exceptional event:

The complete DecodeHeader method is compiled and executed by the documentation example runner:

private static void DecodeHeader()
{
    var layout = new CStruct("struct header { uint16 kind; uint32 length; };");
    ReadOnlySpan<byte> bytes = [0x02, 0x00, 0x06, 0x00, 0x00, 0x00];
    StructValue header = layout.Parse(bytes, "header");
    Equal((ushort)2, header.Get<ushort>("kind"));
    Equal(6U, header.Get<uint>("length"));

    bool read = layout.TryReadValue<Header>(bytes, "header", out Header? typed);
    True(read && typed is { Kind: 2, Length: 6 }, "Typed header result differed.");
    True(!layout.TryReadValue<Header>(bytes[..1], "header", out _), "Truncated TryReadValue should fail.");
}

Remarks

Layout compilation is immutable after construction, so one instance can be reused instead of reparsing the layout for every record. Each operation snapshots caller variables and option values. Stream overloads start at the current position; memory overloads use the start of the supplied region as coordinate zero.

Constructors

CStruct(string, byte, bool, bool, CStructCompilationOptions?)

Creates a reusable layout from C-like source text. Choose the pointer width, alignment rule, and byte order used by numeric values, pointers, and neutral UTF-16 character data in the binary format being handled.

public CStruct(string layout, byte pointerSize = 8, bool aligned = false, bool isLittleEndian = true, CStructCompilationOptions? compilationOptions = null)

Parameters

layout string: The Portable v1 layout source to compile.
pointerSize byte: The binary format's pointer width in bytes; supported values are 1, 2, 4, and 8.
aligned bool: true to apply the portable composite-alignment rules; otherwise, false.
isLittleEndian bool: true for little-endian neutral values; false for big-endian neutral values.
compilationOptions CStructCompilationOptions: Optional resource limits for parsing and compiling the layout; null uses the documented defaults.

Exceptions

ArgumentNullException: layout is null.
ArgumentOutOfRangeException: pointerSize is unsupported, or a compilation limit is not positive.
CStructLayoutException: The layout is empty, exceeds a configured limit, or is not valid Portable v1 syntax.

Properties

Aligned

Gets whether composite fields use their portable alignment boundaries.

public bool Aligned { get; }

Property Value

bool

CompilationOptions

Gets the compilation options this layout was built with (the defaults when none were supplied).

public CStructCompilationOptions CompilationOptions { get; }

Property Value

CStructCompilationOptions

Constants

Gets every #define of the layout by name: integer constants (evaluated without caller variables), text and byte literals, bare names, and function-like macros kept as text. Only integer constants take part in layout expressions.

public IReadOnlyDictionary<string, LayoutConstant> Constants { get; }

Property Value

IReadOnlyDictionary<string, LayoutConstant>

DefaultRoot

Gets the name of the first struct or union declared in the layout: the root that every read operation selects when its path argument is null, and the one to pass to Serialize or Write for a whole-record write.

public string DefaultRoot { get; }

Property Value

string

Exceptions

CStructLayoutException: The layout declares no struct or union.

Includes

Gets the paths of the layout's #include lines in source order, exactly as written. They are recorded for the caller's benefit only; the core never reads or resolves them.

public IReadOnlyList<string> Includes { get; }

Property Value

IReadOnlyList<string>

IsLittleEndian

Gets whether neutral numeric, pointer, and UTF-16 values use little-endian byte order.

public bool IsLittleEndian { get; }

Property Value

bool

Layout

Gets the declarations, fields, offsets, sizes, and members of this layout. Built from the compiled model on first use and cached; a layout that is never inspected pays only the deferred slot.

public LayoutInfo Layout { get; }

Property Value

LayoutInfo

PointerSize

Gets the configured pointer storage width: 1, 2, 4, or 8 bytes.

public byte PointerSize { get; }

Property Value

byte

Methods

ClearCompiledCache()

Removes every layout retained by GetOrCompile(string, byte, bool, bool, CStructCompilationOptions?); instances already handed out stay valid.

public static void ClearCompiledCache()

GetArrayLength(ReadOnlySequence<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Returns the element or character count a path selects within a byte span.

public int GetArrayLength(ReadOnlySequence<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive path of an array or string field.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

int: The number of elements in the selected array or of characters in the selected string.

Exceptions

CStructPathException: The path is invalid or does not select an array or string.
CStructReadException: The stream cannot provide the bytes required to resolve the count.

GetArrayLength(byte[], string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Returns the element or character count a path selects within a byte array.

public int GetArrayLength(byte[] source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive path of an array or string field.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

int: The number of elements in the selected array or of characters in the selected string.

Exceptions

CStructPathException: The path is invalid or does not select an array or string.
CStructReadException: The stream cannot provide the bytes required to resolve the count.
ArgumentNullException: source is null.

GetArrayLength(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Returns the element count of the array, or the character count of the string, a path selects, reading only what determines it. The stream position is restored afterwards.

public int GetArrayLength(Stream stream, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive path of an array or string field.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

int: The number of elements in the selected array or of characters in the selected string.

Exceptions

CStructPathException: The path is invalid or does not select an array or string.
CStructReadException: The stream cannot provide the bytes required to resolve the count.

GetArrayLength(ReadOnlyMemory<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Returns the element or character count a path selects within read-only memory.

public int GetArrayLength(ReadOnlyMemory<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive path of an array or string field.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

int: The number of elements in the selected array or of characters in the selected string.

Exceptions

CStructPathException: The path is invalid or does not select an array or string.
CStructReadException: The stream cannot provide the bytes required to resolve the count.

GetArrayLength(ReadOnlySpan<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Returns the element or character count a path selects within a byte span.

public int GetArrayLength(ReadOnlySpan<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive path of an array or string field.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

int: The number of elements in the selected array or of characters in the selected string.

Exceptions

CStructPathException: The path is invalid or does not select an array or string.
CStructReadException: The stream cannot provide the bytes required to resolve the count.

GetArrayLengthAsync(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Counts a fixed or runtime array's elements (or a terminated string's characters) without reading them; the stream ends at its origin.

public ValueTask<int> GetArrayLengthAsync(Stream stream, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables.
options ReadOptions: Optional read limits and pointer settings.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<int>: The position.

GetOrCompile(string, byte, bool, bool, CStructCompilationOptions?)

Returns a compiled layout for the given source and options, reusing a process-wide bounded cache of the most recently used layouts. Use this instead of the constructor when the same definition text is compiled repeatedly (for example once per message); callers that already keep a CStruct instance gain nothing. The returned instance is shared and immutable, exactly like any other CStruct.

public static CStruct GetOrCompile(string layout, byte pointerSize = 8, bool aligned = false, bool isLittleEndian = true, CStructCompilationOptions? compilationOptions = null)

Parameters

layout string: The Portable v1 layout source to compile.
pointerSize byte: The binary format's pointer width in bytes; supported values are 1, 2, 4, and 8.
aligned bool: true to apply the portable composite-alignment rules; otherwise, false.
isLittleEndian bool: true for little-endian neutral values; false for big-endian neutral values.
compilationOptions CStructCompilationOptions: Optional resource limits for parsing and compiling the layout; every limit is part of the cache key.

Returns

CStruct: A compiled layout equal to new CStruct(layout, pointerSize, aligned, isLittleEndian, compilationOptions).

Exceptions

ArgumentNullException: layout is null.
ArgumentOutOfRangeException: pointerSize is unsupported, or a compilation limit is not positive.
CStructLayoutException: The layout is empty, exceeds a configured limit, or is not valid Portable v1 syntax.

GetStructAlignmentInBytes(string)

Gets the alignment in bytes of a declared struct or union.

public int GetStructAlignmentInBytes(string name)

Parameters

name string: The declaration name.

Returns

int: The alignment in bytes.

GetStructSizeInBytes(string)

Gets the fixed size in bytes of a declared struct or union.

public int GetStructSizeInBytes(string name)

Parameters

name string: The declaration name.

Returns

int: The size in bytes.

Exceptions

CStructLayoutException: The struct has a runtime-sized member.

Parse(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte span; pointer positions are zero-based within the span.

public StructValue Parse(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

StructValue: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

Parse(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte array without copying it.

public StructValue Parse(byte[] source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

StructValue: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.
ArgumentNullException: source is null.

Parse(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct (a root or a nested struct selected by path) into a StructValue.

public StructValue Parse(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

StructValue: The struct's values, readable as dynamic, by name, or through StructValue.Get<T>.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct (use ReadValue(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?) for those).
CStructReadException: The stream cannot provide or decode the required bytes.

Parse(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from read-only memory; the memory is not retained after the call returns.

public StructValue Parse(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

StructValue: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

Parse(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte span; pointer positions are zero-based within the span.

public StructValue Parse(ReadOnlySpan<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

StructValue: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

ParseAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads a struct (a root or a nested struct selected by path) into a StructValue; see the class remarks for the stream rules.

public ValueTask<StructValue> ParseAsync(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<StructValue>: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

ParseMany(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads the records of a ReadOnlySequence<T>: a single segment is read in place, a chain of segments through one pooled copy that lives as long as the enumeration.

public IEnumerable<StructValue> ParseMany(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The bytes of the records, with nothing else after them.
path string: The case-sensitive name of the root struct each record is; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings, applied to every record; null uses the documented defaults.

Returns

IEnumerable<StructValue>: The records, parsed as they are enumerated.

Exceptions

CStructPathException: path does not name a struct declaration (a union or scalar root is read with ReadValue).
CStructReadException: A record cannot be read, or the trailing bytes are shorter than one record; raised by the enumeration that reaches it.

ParseMany(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads the records of a seekable stream from its current position to its end with the stream reader, one record per enumeration step, byte-exact: the stream is left after the last record read, or where a failed read stopped. A stream that cannot seek is read with ParseManyAsync.

public IEnumerable<StructValue> ParseMany(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the first record's start.
path string: The case-sensitive name of the root struct each record is; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings, applied to every record; null uses the documented defaults.

Returns

IEnumerable<StructValue>: The records, parsed as they are enumerated.

Exceptions

ArgumentException: stream cannot be read or cannot seek.
CStructPathException: path does not name a struct declaration.
CStructReadException: A record cannot be read, or the trailing bytes are shorter than one record; raised by the enumeration that reaches it.

ParseMany(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads the records of source lazily: one root struct after another until the memory ends; see the class remarks for the trailing-bytes and pointer rules.

public IEnumerable<StructValue> ParseMany(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The bytes of the records, with nothing else after them.
path string: The case-sensitive name of the root struct each record is; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings, applied to every record; null uses the documented defaults.

Returns

IEnumerable<StructValue>: The records, parsed as they are enumerated.

Exceptions

CStructPathException: path does not name a struct declaration (a union or scalar root is read with ReadValue).
CStructReadException: A record cannot be read, or the trailing bytes are shorter than one record; raised by the enumeration that reaches it.

ParseManyAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads the records of a stream with ReadAsync(Memory<byte>, CancellationToken). A root with a fixed size is read exactly one record at a time, so any readable stream serves, byte-exact; a runtime-sized root is read through a pooled window of the bytes left (at most MaxTotalBytesRead plus one) that refills from the start of a record it could not hold, which needs a seekable stream. After each record a seekable stream sits at the record's end.

public IAsyncEnumerable<StructValue> ParseManyAsync(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the first record's start.
path string: The case-sensitive name of the root struct each record is; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings, applied to every record; null uses the documented defaults.
cancellationToken CancellationToken: Ends the enumeration while it waits for bytes, between records, or at the next boundary the reader checks; linked with CancellationToken.

Returns

IAsyncEnumerable<StructValue>: The records, parsed as they are enumerated.

Exceptions

ArgumentException: stream cannot be read, or cannot seek while the root has no fixed size.
CStructPathException: path does not name a struct declaration.
CStructReadException: A record cannot be read, or the trailing bytes are shorter than one record; raised by the enumeration that reaches it.
OperationCanceledException: The token was cancelled.

ParseWithDebug(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte span and records the byte range of every value read.

public ParseResult ParseWithDebug(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ParseResult: The struct's values and the debug records.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

ParseWithDebug(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte array and records the byte range of every value read.

public ParseResult ParseWithDebug(byte[] source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ParseResult: The struct's values and the debug records.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.
ArgumentNullException: source is null.

ParseWithDebug(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct exactly like Parse(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?) and also records the byte range of every value read. Debug reads need a seekable stream.

public ParseResult ParseWithDebug(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ParseResult: The struct's values and the debug records.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

ParseWithDebug(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from read-only memory and records the byte range of every value read.

public ParseResult ParseWithDebug(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ParseResult: The struct's values and the debug records.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

ParseWithDebug(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads a struct from a byte span and records the byte range of every value read.

public ParseResult ParseWithDebug(ReadOnlySpan<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ParseResult: The struct's values and the debug records.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The region cannot provide or decode the required bytes.

ParseWithDebugAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads a struct and records the byte range of every value; the ranges are stream coordinates (the origin is added) for a seekable stream and buffer offsets for a non-seekable one.

public ValueTask<ParseResult> ParseWithDebugAsync(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<ParseResult>: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

ReadValue(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span in its natural representation.

public object? ReadValue(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

object: A StructValue, UnionValue, scalar, string, PrimitiveArray<T> or list, Pointer, or EnumValueResult.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValue(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte array in its natural representation.

public object? ReadValue(byte[] source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

object: A StructValue, UnionValue, scalar, string, PrimitiveArray<T> or list, Pointer, or EnumValueResult.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.
ArgumentNullException: source is null.

ReadValue(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value - a root, a field, an array element, a pointer accessor, or a nested object - in its natural representation without materializing unrelated siblings.

public object? ReadValue(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

object: A StructValue, UnionValue, scalar, string, PrimitiveArray<T> or list, Pointer, or EnumValueResult.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The stream cannot provide or decode the required bytes.

ReadValue(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from read-only memory in its natural representation.

public object? ReadValue(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

object: A StructValue, UnionValue, scalar, string, PrimitiveArray<T> or list, Pointer, or EnumValueResult.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValue(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span in its natural representation.

public object? ReadValue(ReadOnlySpan<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

object: A StructValue, UnionValue, scalar, string, PrimitiveArray<T> or list, Pointer, or EnumValueResult.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValueAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads the natural value of any selection (a struct, union, array, scalar, enum, or pointer part); see the class remarks for the stream rules.

public ValueTask<object?> ReadValueAsync(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<object>: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

ReadValueAsync<T>(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads a selection and maps it to T with the conversions of Get<T>; see the class remarks for the stream rules.

public ValueTask<T> ReadValueAsync<T>(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<T>: The struct's values.

Type Parameters

T: The requested value type.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

ReadValueWithDebug(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span and records the byte range of every value read.

public ReadResult ReadValueWithDebug(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ReadResult: The value at the path and the debug records.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValueWithDebug(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte array and records the byte range of every value read.

public ReadResult ReadValueWithDebug(byte[] source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ReadResult: The value at the path and the debug records.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.
ArgumentNullException: source is null.

ReadValueWithDebug(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value exactly like ReadValue(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?) and also records the byte range of every value read. Debug reads need a seekable stream.

public ReadResult ReadValueWithDebug(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ReadResult: The value at the path and the debug records.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValueWithDebug(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from read-only memory and records the byte range of every value read.

public ReadResult ReadValueWithDebug(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ReadResult: The value at the path and the debug records.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValueWithDebug(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span and records the byte range of every value read.

public ReadResult ReadValueWithDebug(ReadOnlySpan<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

ReadResult: The value at the path and the debug records.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide or decode the required bytes.

ReadValueWithDebugAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Reads the natural value of any selection and records the byte range of every value read; see ParseWithDebugAsync(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken) for the coordinates.

public ValueTask<ReadResult> ReadValueWithDebugAsync(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<ReadResult>: The struct's values.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

ReadValue<T>(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span and maps it to T.

public T ReadValue<T>(ReadOnlySequence<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

T: The selected value converted or bound to T.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The bytes cannot be decoded or the result cannot be bound to T.

ReadValue<T>(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte array and maps it to T.

public T ReadValue<T>(byte[] source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

T: The selected value converted or bound to T.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The bytes cannot be decoded or the result cannot be bound to T.
ArgumentNullException: source is null.

ReadValue<T>(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value and maps it to T: a scalar with a checked conversion, or a struct bound to a class or record whose public writable members match the field names without regard to case. Unsupported or lossy conversions fail with CStructReadException.

public T ReadValue<T>(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

T: The selected value converted or bound to T.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The bytes cannot be decoded or the result cannot be bound to T.

ReadValue<T>(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from read-only memory and maps it to T.

public T ReadValue<T>(ReadOnlyMemory<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

T: The selected value converted or bound to T.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The bytes cannot be decoded or the result cannot be bound to T.

ReadValue<T>(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Reads one value from a byte span and maps it to T.

public T ReadValue<T>(ReadOnlySpan<byte> source, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

T: The selected value converted or bound to T.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The bytes cannot be decoded or the result cannot be bound to T.

ResolveAddress(ReadOnlySequence<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Finds the offset of a path within a byte span without reading its value.

public long ResolveAddress(ReadOnlySequence<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path to locate.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional traversal limits and pointer settings; null uses the documented defaults.

Returns

long: The zero-based offset of the selected field or pointer target within source.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide the bytes required for traversal.

ResolveAddress(byte[], string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Finds the offset of a path within a byte array without reading its value.

public long ResolveAddress(byte[] source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path to locate.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional traversal limits and pointer settings; null uses the documented defaults.

Returns

long: The zero-based offset of the selected field or pointer target within source.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide the bytes required for traversal.
ArgumentNullException: source is null.

ResolveAddress(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Finds the position of a path without reading its value. A path ending in .value resolves to the pointer target; one ending in .address resolves to the pointer field itself. The stream position is restored afterwards.

public long ResolveAddress(Stream stream, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path to locate.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional traversal limits and pointer settings; null uses the documented defaults.

Returns

long: The absolute stream position of the selected field or pointer target.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide the bytes required for traversal.

ResolveAddress(ReadOnlyMemory<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Finds the offset of a path within read-only memory without reading its value.

public long ResolveAddress(ReadOnlyMemory<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path to locate.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional traversal limits and pointer settings; null uses the documented defaults.

Returns

long: The zero-based offset of the selected field or pointer target within source.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide the bytes required for traversal.

ResolveAddress(ReadOnlySpan<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Finds the offset of a path within a byte span without reading its value.

public long ResolveAddress(ReadOnlySpan<byte> source, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path to locate.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional traversal limits and pointer settings; null uses the documented defaults.

Returns

long: The zero-based offset of the selected field or pointer target within source.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructReadException: The region cannot provide the bytes required for traversal.

ResolveAddressAsync(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Finds a path's position without reading its value; a stream coordinate (the origin is added) for a seekable stream, a buffer offset for a non-seekable one. The stream ends at its origin either way.

public ValueTask<long> ResolveAddressAsync(Stream stream, string path, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables.
options ReadOptions: Optional read limits and pointer settings.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<long>: The position.

Serialize(IBufferWriter<byte>, string, object, IReadOnlyDictionary<string, int>?, WriteOptions?)

Appends the encoded value to an IBufferWriter<T> and returns the number of bytes appended. Pointer coordinates are relative to the start of the appended region; windows already advanced cannot be retracted after a later failure.

public long Serialize(IBufferWriter<byte> destination, string path, object value, IReadOnlyDictionary<string, int>? variables = null, WriteOptions? options = null)

Parameters

destination IBufferWriter<byte>: The caller-owned buffer writer to append to.
path string: The case-sensitive root name or nested field path to serialize.
value object: The value to encode.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options WriteOptions: Optional write limits, unknown-member policy, and pointer settings; null uses the documented defaults.

Returns

long: The number of bytes appended.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value cannot be encoded.

Serialize(Span<byte>, string, object, IReadOnlyDictionary<string, int>?, WriteOptions?)

Serializes into caller-owned storage and returns the number of bytes initialized at its start. Excess capacity is left unchanged; insufficient capacity fails with CStructWriteException after a prefix may already have been written. Pointer coordinates are zero-based within the destination.

public int Serialize(Span<byte> destination, string path, object value, IReadOnlyDictionary<string, int>? variables = null, WriteOptions? options = null)

Parameters

destination Span<byte>: Caller-owned storage that receives the encoded bytes.
path string: The case-sensitive root name or nested field path to serialize.
value object: The value to encode.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options WriteOptions: Optional write limits, unknown-member policy, and pointer settings; null uses the documented defaults.

Returns

int: The number of bytes written at the start of destination.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value is invalid or the destination is too small; an initialized prefix may remain.

Serialize(string, object, IReadOnlyDictionary<string, int>?, WriteOptions?)

Creates a new byte array holding value encoded as the declaration or nested field path selects. The value may be a StructValue from a parse, a dictionary, an instance of a class implementing ICStructMapped<TSelf>, or a scalar for a scalar path.

public byte[] Serialize(string path, object value, IReadOnlyDictionary<string, int>? variables = null, WriteOptions? options = null)

Parameters

path string: The case-sensitive root name or nested field path to serialize.
value object: The value to encode.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options WriteOptions: Optional write limits, unknown-member policy, and pointer settings; null uses the documented defaults.

Returns

byte[]: An exactly sized array; no partial output survives a failure.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value cannot be encoded.

ToDefinition()

Renders the compiled layout back to Portable text (declarations in their compiled order).

public string ToDefinition()

Returns

string: The layout definition that compiles to this layout's model.

TryReadValueAsync<T>(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

The non-throwing form of ReadValueAsync<T>(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken): a categorized read, path, or limit failure becomes a ReadAttempt<T> with Failure set and a seekable stream back at its origin. Cancellation and argument errors throw as everywhere else.

public ValueTask<ReadAttempt<T>> TryReadValueAsync<T>(Stream stream, string? path = null, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable stream whose current position is the operation origin.
path string: The case-sensitive root name or nested path; null selects the first declared struct.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the read while it waits for bytes or at the next boundary the reader checks.

Returns

ValueTask<ReadAttempt<T>>: The struct's values.

Type Parameters

T: The requested value type.

Exceptions

CStructPathException: The path is invalid, or selects a union or scalar rather than a struct.
CStructReadException: The stream cannot provide or decode the required bytes.
OperationCanceledException: The token was cancelled.

TryReadValue<T>(ReadOnlySequence<byte>, string?, out T, IReadOnlyDictionary<string, int>?, ReadOptions?)

Attempts a typed read from a byte span; an expected CStructSharp failure returns false.

public bool TryReadValue<T>(ReadOnlySequence<byte> source, string? path, out T value, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySequence<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
value T: Receives the typed result on success, or the default value of T on failure.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

bool: true on success; false for a categorized CStructSharp failure.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

TryReadValue<T>(byte[], string?, out T, IReadOnlyDictionary<string, int>?, ReadOptions?)

Attempts a typed read from a byte array; an expected CStructSharp failure returns false.

public bool TryReadValue<T>(byte[] source, string? path, out T value, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source byte[]: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
value T: Receives the typed result on success, or the default value of T on failure.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

bool: true on success; false for a categorized CStructSharp failure.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

ArgumentNullException: source is null.

TryReadValue<T>(Stream, string?, out T, IReadOnlyDictionary<string, int>?, ReadOptions?)

Attempts ReadValue<T>(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?). An expected layout, path, read, or conversion failure returns false and restores the stream position from before the attempt; invalid arguments and unexpected failures still throw.

public bool TryReadValue<T>(Stream stream, string? path, out T value, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

stream Stream: The readable, seekable stream whose position is restored after an expected failure.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
value T: Receives the typed result on success, or the default value of T on failure.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

bool: true on success; false for a categorized CStructSharp failure.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Exceptions

ArgumentException: stream is not readable and seekable.

TryReadValue<T>(ReadOnlyMemory<byte>, string?, out T, IReadOnlyDictionary<string, int>?, ReadOptions?)

Attempts a typed read from read-only memory; an expected CStructSharp failure returns false.

public bool TryReadValue<T>(ReadOnlyMemory<byte> source, string? path, out T value, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlyMemory<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
value T: Receives the typed result on success, or the default value of T on failure.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

bool: true on success; false for a categorized CStructSharp failure.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

TryReadValue<T>(ReadOnlySpan<byte>, string?, out T, IReadOnlyDictionary<string, int>?, ReadOptions?)

Attempts a typed read from a byte span; an expected CStructSharp failure returns false.

public bool TryReadValue<T>(ReadOnlySpan<byte> source, string? path, out T value, IReadOnlyDictionary<string, int>? variables = null, ReadOptions? options = null)

Parameters

source ReadOnlySpan<byte>: The complete byte region available to this operation.
path string: The case-sensitive root name or nested path; null selects the first declared struct or union.
value T: Receives the typed result on success, or the default value of T on failure.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options ReadOptions: Optional read limits and pointer settings; null uses the documented defaults.

Returns

bool: true on success; false for a categorized CStructSharp failure.

Type Parameters

T: The destination type: a scalar, string, enum, array, StructValue, UnionValue, Pointer, or a class implementing ICStructMapped<TSelf>.

Update(Stream, string, object, IReadOnlyDictionary<string, int>?, UpdateOptions?)

Replaces one value that already exists in the data: the path is located, the replacement is validated against the existing storage, and only then are its bytes committed. Later fields never move, so the replacement must fit the existing storage plan. The stream position is restored afterwards.

public void Update(Stream stream, string path, object value, IReadOnlyDictionary<string, int>? variables = null, UpdateOptions? options = null)

Parameters

stream Stream: The readable, writable, seekable stream whose current position is the operation origin.
path string: The case-sensitive path of the value to replace.
value object: The replacement value.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options UpdateOptions: Optional traversal limits, pointer rules, and union handling; null uses the documented defaults.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The replacement does not fit or cannot be encoded; the stream is unchanged unless a physical commit failed.

Update(Span<byte>, string, object, IReadOnlyDictionary<string, int>?, UpdateOptions?)

Replaces one value in place inside a byte span (a byte array binds here too). Pointer coordinates are zero-based within the span, and the span's length cannot change.

public void Update(Span<byte> data, string path, object value, IReadOnlyDictionary<string, int>? variables = null, UpdateOptions? options = null)

Parameters

data Span<byte>: The bytes to change in place.
path string: The case-sensitive path of the value to replace.
value object: The replacement value.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options UpdateOptions: Optional traversal limits, pointer rules, and union handling; null uses the documented defaults.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The replacement does not fit or cannot be encoded; the span is unchanged.

UpdateAsync(Stream, string, object, IReadOnlyDictionary<string, int>?, UpdateOptions?, CancellationToken)

Locates a value in the stream's existing bytes and replaces it in place: the region from the current position is read into a buffer, validated and updated there, and only the changed ranges are written back. The stream must be seekable; the position is the origin afterwards.

public ValueTask UpdateAsync(Stream stream, string path, object value, IReadOnlyDictionary<string, int>? variables = null, UpdateOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The readable, writable, seekable stream; the current position is the region's origin.
path string: The case-sensitive root name or nested field path to replace.
value object: The replacement value.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables.
options UpdateOptions: Optional update limits and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the update before the read, during the staged validation, or before the write-back; linked with CancellationToken.

Returns

ValueTask: A task that completes when the changed bytes have been written.

Remarks

Acquisition failures restore the origin without writing. If restoration itself fails while handling an earlier failure, the original exception is preserved and the position cannot be guaranteed. I/O failure during write-back can leave some ranges changed; this is not a transactional write.

Exceptions

ArgumentException: The stream cannot seek: the changed bytes are written back in place.
CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value cannot be encoded; the stream is unchanged.

WithAlignment(bool)

Returns a layout compiled from the same source and options with the requested placement rule.

public CStruct WithAlignment(bool aligned)

Parameters

aligned bool: true for the portable composite-alignment rules; false for packed placement.

Returns

CStruct: This layout when the rule already matches; otherwise the sibling layout.

WithEndianness(bool)

Returns a layout compiled from the same source and options with the requested byte order - for a format whose header says which order the rest of the file uses. Repeated calls return the cached instance.

public CStruct WithEndianness(bool isLittleEndian)

Parameters

isLittleEndian bool: true for little-endian neutral values; false for big-endian.

Returns

CStruct: This layout when the byte order already matches; otherwise the sibling layout.

WithPointerSize(byte)

Returns a layout compiled from the same source and options with the requested pointer width.

public CStruct WithPointerSize(byte pointerSize)

Parameters

pointerSize byte: The pointer width in bytes: 1, 2, 4, or 8.

Returns

CStruct: This layout when the width already matches; otherwise the sibling layout.

Write(Stream, string, object, IReadOnlyDictionary<string, int>?, WriteOptions?)

Writes the encoded value to a writable, seekable stream starting at its current position. Fields written before a later failure remain in the stream.

public void Write(Stream stream, string path, object value, IReadOnlyDictionary<string, int>? variables = null, WriteOptions? options = null)

Parameters

stream Stream: The writable, seekable destination; writing starts at its current position.
path string: The case-sensitive root name or nested field path to write.
value object: The value to encode.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options WriteOptions: Optional write limits, unknown-member policy, and pointer settings; null uses the documented defaults.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value cannot be encoded; earlier fields may already be written.

WriteAsync(Stream, string, object, IReadOnlyDictionary<string, int>?, WriteOptions?, CancellationToken)

Serializes a root or selected value and writes it at the stream's current position.

public ValueTask WriteAsync(Stream stream, string path, object value, IReadOnlyDictionary<string, int>? variables = null, WriteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The writable stream; the current position is the output origin.
path string: The case-sensitive root name or nested field path to write.
value object: The value to encode: a StructValue, a dictionary, a registered mapped class, or a scalar for a scalar path.
variables IReadOnlyDictionary<string, int>: Optional per-operation integer layout variables; entries are snapshotted and never mutated.
options WriteOptions: Optional write limits, unknown-member policy, and pointer settings; null uses the documented defaults.
cancellationToken CancellationToken: Ends the write before the bytes are sent or at the next boundary the writer checks; linked with CancellationToken.

Returns

ValueTask: A task that completes when the bytes have been written.

Exceptions

CStructPathException: The path is invalid or cannot be resolved.
CStructWriteException: The value cannot be encoded; nothing was written.
OperationCanceledException: The token was cancelled.

Table of Contents

Class CStruct

Examples

Remarks

Constructors

CStruct(string, byte, bool, bool, CStructCompilationOptions?)

Parameters

Exceptions

Properties

Aligned

Property Value

CompilationOptions

Property Value

Constants

Property Value

DefaultRoot

Property Value

Exceptions

Includes

Property Value

IsLittleEndian

Property Value

Layout

Property Value

PointerSize

Property Value

Methods

ClearCompiledCache()

GetArrayLength(ReadOnlySequence<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

GetArrayLength(byte[], string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

GetArrayLength(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

GetArrayLength(ReadOnlyMemory<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

GetArrayLength(ReadOnlySpan<byte>, string, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

GetArrayLengthAsync(Stream, string, IReadOnlyDictionary<string, int>?, ReadOptions?, CancellationToken)

Parameters

Returns

GetOrCompile(string, byte, bool, bool, CStructCompilationOptions?)

Parameters

Returns

Exceptions

GetStructAlignmentInBytes(string)

Parameters

Returns

GetStructSizeInBytes(string)

Parameters

Returns

Exceptions

Parse(ReadOnlySequence<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

Parse(byte[], string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

Parse(Stream, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

Parse(ReadOnlyMemory<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters

Returns

Exceptions

Parse(ReadOnlySpan<byte>, string?, IReadOnlyDictionary<string, int>?, ReadOptions?)

Parameters