Class WriteOptions

Namespace

CStructSharp

Assembly

CStructSharp.dll

Controls serialization and stream-writing operations performed by CStruct.

public record WriteOptions : IEquatable<WriteOptions>

Inheritance

object

WriteOptions

Implements

IEquatable<WriteOptions>

Derived

UpdateOptions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

Serialize to caller-owned memory when you want to control allocation. The span overload reports how many bytes it used; the buffer-writer overload appends exactly the produced bytes:

The RoundTrip scenario is compiled and executed with sentinel bytes that detect an overrun:

private static void RoundTrip()
{
    var layout = new CStruct("struct sample { uint16 id; uint8 flags; };");
    byte[] input = [0x34, 0x12, 0xA5];
    object parsed = layout.Parse(input, "sample");
    SequenceEqual(input, layout.Serialize("sample", parsed));

    Span<byte> destination = stackalloc byte[8];
    destination.Fill(0xCC);
    int written = layout.Serialize(destination, "sample", parsed);
    Equal(3, written);
    SequenceEqual(input, destination[..written].ToArray());
    Equal((byte)0xCC, destination[written]);

    var writer = new ArrayBufferWriter<byte>();
    Equal(3L, layout.Serialize(writer, "sample", parsed));
    SequenceEqual(input, writer.WrittenSpan.ToArray());
}

Remarks

Every operation snapshots these values before writing (see SnapshotWriteOptions(WriteOptions)) using this record's own with expression rather than a hand-maintained property-by-property copy, so a newly added property is always included in the snapshot automatically. Budgets are per public operation. Stream operations use the stream's current position as their output origin; caller-owned memory uses coordinate zero. Left unsealed only so UpdateOptions can derive from it while keeping the same snapshot-via-with pattern; ReadOptions has no such subtype and stays sealed.

Constructors

WriteOptions()

Creates the default bounded write policy.

public WriteOptions()

WriteOptions(WriteOptions)

protected WriteOptions(WriteOptions original)

Parameters

original WriteOptions

Properties

AddressingMode

Gets whether written pointer values are absolute stream positions or offsets from Origin.

public PointerAddressingMode AddressingMode { get; init; }

Property Value

PointerAddressingMode

CancellationToken

Gets the token a long write observes: it is checked when a composite or a pointer target is entered and per element of a composite array, and a cancelled token ends the operation with OperationCanceledException before the destination is committed (an update stages first; a direct stream write may have written a prefix, as any late failure may).

public CancellationToken CancellationToken { get; init; }

Property Value

CancellationToken

EqualityContract

protected virtual Type EqualityContract { get; }

Property Value

Type

MaxArrayElements

Gets the greatest number of elements one array field may write.

public int MaxArrayElements { get; init; }

Property Value

int

MaxNestingDepth

Gets the greatest active struct or union depth one write operation may enter.

public int MaxNestingDepth { get; init; }

Property Value

int

MaxStringBytes

Gets the greatest encoded-byte length one string field may write, including fixed-buffer padding or a terminated string's complete terminator.

public long MaxStringBytes { get; init; }

Property Value

long

MaxTotalBytesWritten

Gets the greatest total number of bytes one operation may physically submit to its stream. Rewrites of shared storage count again, and extending a seekable stream across a gap is charged by extent.

public long MaxTotalBytesWritten { get; init; }

Property Value

long

Origin

Gets the base position subtracted, with checked arithmetic, from relative pointer values before they are written. The resulting non-null offset must be positive and fit the configured pointer width. Null address zero is stored directly and does not use this origin.

public long Origin { get; init; }

Property Value

long

UnknownMembers

Gets what happens when the supplied value carries a member the struct or union does not declare - a misspelled key, a stale property, or an extra dictionary entry. The default ignores it; Reject fails the write with the unknown name and the declared members, checked per composite before its bytes are written. Parsed UnionValue instances are never checked.

public UnknownMemberPolicy UnknownMembers { get; init; }

Property Value

UnknownMemberPolicy

Methods

Equals(WriteOptions?)

public virtual bool Equals(WriteOptions? other)

Parameters

other WriteOptions

Returns

bool

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

PrintMembers(StringBuilder)

protected virtual bool PrintMembers(StringBuilder builder)

Parameters

builder StringBuilder

Returns

bool

ToString()

public override string ToString()

Returns

string

Operators

operator ==(WriteOptions?, WriteOptions?)

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

Parameters

left WriteOptions

right WriteOptions

Returns

bool

operator !=(WriteOptions?, WriteOptions?)

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

Parameters

left WriteOptions

right WriteOptions

Returns

bool