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
-
ReadOptions
- Implements
- Inherited Members
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
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
ConstraintViolations
Gets the collection that receives every @expect and @supports failure instead of the first one
ending the read: when it is set, a field whose value breaks a constraint adds a
CStructConstraintException (not thrown, with the member, path and offset
of a thrown one) and the read continues with the value as read, so one pass reports every inconsistent field
of a header. Any other failure (a short read, a limit, an expression that cannot be evaluated) still ends the read
with its exception, and a read that completes with an empty collection satisfied every constraint. Constraints are
checked in field order, so the list is in field order. null, the default, throws the first.
public ICollection<CStructConstraintException>? ConstraintViolations { get; init; }Property Value
Remarks
A value that breaks a constraint may break what depends on it (a count that is too large fails the array limit next); the collection then holds the failures found up to that read failure, which is thrown as usual. The collection is not thread-safe and is added to in place: use one per read.
Constraints
Gets whether the read evaluates the @expect and @supports constraints of its layout. The default,
Enforce, evaluates them (and collects them when ConstraintViolations is set);
Skip evaluates none and collects nothing. Setting Skip together
with ConstraintViolations is contradictory and fails with ArgumentException when the read starts.
public ConstraintPolicy Constraints { get; init; }Property Value
Remarks
See ConstraintPolicy: a skipped condition may be one that later code relies on.
Exceptions
- ArgumentOutOfRangeException
The value is not a member of ConstraintPolicy.
DereferencePointers
Gets whether non-null pointers are followed while parsing.
public bool DereferencePointers { get; init; }Property Value
InvalidText
Gets what a read does with text that is not valid in its encoding: Fail
(the default) reports the field, Replace reads each invalid sequence as
U+FFFD and continues. It applies to utf8 and UTF-16 buffers, wchar[N], and terminated strings;
see InvalidTextHandling. Writing is unaffected: text that cannot be encoded still fails.
public InvalidTextHandling InvalidText { get; init; }Property Value
Exceptions
- ArgumentOutOfRangeException
The value is not a member of InvalidTextHandling.
MaxArrayElements
Gets the greatest number of elements a single traversed array field may contain.
public int MaxArrayElements { get; init; }Property Value
MaxNestingDepth
Gets the greatest active struct depth permitted during one read-like operation.
public int MaxNestingDepth { get; init; }Property Value
MaxPointerDepth
Gets the greatest number of nested pointer dereferences allowed on one parse branch.
public int MaxPointerDepth { get; init; }Property Value
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
MaxTotalBytesRead
Gets the greatest total bytes one public read-like operation may consume. Each byte a read consumes counts once; a byte read again (a pointer target visited twice, a union's overlapping members) counts again. Bytes inspected before they are consumed do not count: the scan of a terminated array for its terminator, and the read-ahead of a terminated string past its terminator, although a stream source may physically read them. Seeking across a gap or padding 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
Remarks
A parse of struct one { uint8 a[]; } over 01 02 00 consumes the two elements and the terminator,
so it succeeds with a budget of 3 and fails with CStructReadLimitException at 2. The
runtime and the generated readers charge the same bytes on every input form.
OffsetBase
Gets the position of the source's first byte in the larger input it was cut from (an image, a file; for a stream read by a generated reader, the stream's position at the call), added to the Offset every failure of a span, array, memory or generated stream read reports and to the offset in its message, so a failure names where the bytes are in the evidence rather than in the buffer. It changes nothing else: positions, addresses and pointer targets still count from the buffer's first byte, and the runtime layout's stream readers and the record sequences over a stream report absolute stream positions already and ignore it. The default is 0.
public long OffsetBase { get; init; }Property Value
Exceptions
- ArgumentOutOfRangeException
The value is negative or greater than 2^48 - 1 (MaxOffsetBase).
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
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
Methods
Equals(ReadOptions?)
public bool Equals(ReadOptions? other)Parameters
otherReadOptions
Returns
Equals(object?)
public override bool Equals(object? obj)Parameters
objobject
Returns
GetHashCode()
public override int GetHashCode()Returns
ToString()
public override string ToString()Returns
Operators
operator ==(ReadOptions?, ReadOptions?)
public static bool operator ==(ReadOptions? left, ReadOptions? right)Parameters
leftReadOptionsrightReadOptions
Returns
operator !=(ReadOptions?, ReadOptions?)
public static bool operator !=(ReadOptions? left, ReadOptions? right)Parameters
leftReadOptionsrightReadOptions