Class ReadOptions

Namespace

CStructSharp

Assembly

CStructSharp.dll

Controls the safety budgets and pointer policy shared by parsing, debug parsing, selected reads, address resolution, and dynamic-length lookup.

public sealed record ReadOptions : IEquatable<ReadOptions>

Inheritance

object

ReadOptions

Implements

IEquatable<ReadOptions>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

Default read options follow this one-byte pointer while applying the library's normal pointer and traversal limits:

The same FollowPointer method is compiled and executed to check this default:

private static void FollowPointer()
{
    var layout = new CStruct("struct root { uint8 *target; };", pointerSize: 1);
    using var stream = new MemoryStream([0x01, 0x2A]);
    StructValue root = layout.Parse(stream, "root");
    Pointer pointer = root.Get<Pointer>("target");
    Equal(1L, pointer.Address);
    True(pointer.IsDereferenced, "Pointer should be followed by default.");
    Equal((byte)0x2A, (byte)pointer.Value!);
}

Remarks

Every operation snapshots these values before reading. Budgets are per public operation, not lifetime counters, and invalid non-positive limits fail before payload traversal. A record: options with { TrimFixedText = true } copies every other member, and two instances with the same members are equal.

Constructors

ReadOptions()

Creates the default bounded read and pointer policy.

public ReadOptions()

Properties

AddressingMode

Gets whether pointer addresses are stream positions or offsets from Origin.

public PointerAddressingMode AddressingMode { get; init; }

Property Value

PointerAddressingMode

CancellationToken

Gets the token a long read observes: it is checked when a composite or a pointer target is entered, per block of a primitive array, per element of a composite array, and per chunk of a terminated string, and a cancelled token ends the operation with OperationCanceledException (not a read failure: TryReadValue lets it through). Never checked per primitive, so a small read costs nothing for it.

public CancellationToken CancellationToken { get; init; }

Property Value

CancellationToken

DereferencePointers

Gets whether non-null pointers are followed while parsing.

public bool DereferencePointers { get; init; }

Property Value

bool

MaxArrayElements

Gets the greatest number of elements a single traversed array field may contain.

public int MaxArrayElements { get; init; }

Property Value

int

MaxNestingDepth

Gets the greatest active struct depth permitted during one read-like operation.

public int MaxNestingDepth { get; init; }

Property Value

int

MaxPointerDepth

Gets the greatest number of nested pointer dereferences allowed on one parse branch.

public int MaxPointerDepth { get; init; }

Property Value

int

MaxPointerTargetBytes

Gets the greatest fixed-size target, in bytes, that can be read through one pointer. A null value leaves the target size unrestricted. Variable-length string targets are rejected when a limit is set. This is a target's decoded size, never a maximum pointer address or seek distance.

public long? MaxPointerTargetBytes { get; init; }

Property Value

long?

MaxStringBytes

Gets the greatest encoded-byte length permitted for one terminated string field, including its complete encoded terminator.

public long MaxStringBytes { get; init; }

Property Value

long

MaxTotalBytesRead

Gets the greatest total bytes one public read-like operation may physically read. Seeking across a gap does not consume this budget: a small target several terabytes into a file costs only its decoded bytes. Set a larger value, up to MaxValue, when intentionally reading more payload data.

public long MaxTotalBytesRead { get; init; }

Property Value

long

Origin

Gets the signed base position added with checked arithmetic to non-null relative pointer offsets before their target stream range is validated.

public long Origin { get; init; }

Property Value

long

TrimFixedText

Gets whether fixed-capacity text - char[N], wchar[N], and bounded encoded buffers such as utf8 name[N] - drops its trailing NUL padding when read. The default keeps every character, so a char[4] holding 61 62 00 00 reads as "ab\0\0"; with this option it reads as "ab". Only trailing NULs are removed; embedded NULs stay. Writing is unaffected: shorter text is always zero-padded to the declared capacity.

public bool TrimFixedText { get; init; }

Property Value

bool

Methods

Equals(ReadOptions?)

public bool Equals(ReadOptions? other)

Parameters

other ReadOptions

Returns

bool

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

ToString()

public override string ToString()

Returns

string

Operators

operator ==(ReadOptions?, ReadOptions?)

public static bool operator ==(ReadOptions? left, ReadOptions? right)

Parameters

left ReadOptions

right ReadOptions

Returns

bool

operator !=(ReadOptions?, ReadOptions?)

public static bool operator !=(ReadOptions? left, ReadOptions? right)

Parameters

left ReadOptions

right ReadOptions

Returns

bool