Class UpdateOptions

Namespace

CStructSharp

Assembly

CStructSharp.dll

Adds bounded read-side traversal and in-place replacement choices to the normal write options. Updates validate against sparse staging before commit and cannot extend the existing destination stream.

public sealed record UpdateOptions : WriteOptions, IEquatable<WriteOptions>, IEquatable<UpdateOptions>

Inheritance

object

WriteOptions

UpdateOptions

Implements

IEquatable<WriteOptions>

IEquatable<UpdateOptions>

Inherited Members

WriteOptions.AddressingMode

WriteOptions.UnknownMembers

WriteOptions.MaxArrayElements

WriteOptions.MaxStringBytes

WriteOptions.MaxTotalBytesWritten

WriteOptions.CancellationToken

WriteOptions.MaxNestingDepth

WriteOptions.Origin

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Examples

An update changes one selected field while preserving the stream's starting position. The failed update also shows that invalid replacement data does not leave a partial change:

PatchField is compiled and executed for both the successful and failed update:

private static void PatchField()
{
    var layout = new CStruct("struct item { uint16 id; uint8 flags; }; struct root { item value; };");
    using var stream = new MemoryStream([0xEE, 0xEE, 0x34, 0x12, 0x01]);
    stream.Position = 2;
    layout.Update(stream, "root.value.flags", (byte)0xA5);
    SequenceEqual([0xEE, 0xEE, 0x34, 0x12, 0xA5], stream.ToArray());
    Equal(2L, stream.Position);

    byte[] before = stream.ToArray();
    Throws<CStructWriteException>(() => layout.Update(stream, "root.value.flags", 999));
    SequenceEqual(before, stream.ToArray());
    Equal(2L, stream.Position);
}

Remarks

Update operations snapshot both these traversal settings and the inherited WriteOptions values. Library-detectable validation failures occur before destination commit and preserve the caller's stream position.

Constructors

UpdateOptions()

Creates the default bounded update, traversal, and replacement policy.

public UpdateOptions()

Properties

ClearUnionStorage

Gets whether an updated union is cleared before its selected member is written.

public bool ClearUnionStorage { get; init; }

Property Value

bool

DereferencePointers

Gets whether an update path may pass through a pointer's .value target.

public bool DereferencePointers { get; init; }

Property Value

bool

EqualityContract

protected override Type EqualityContract { get; }

Property Value

Type

MaxTraversalArrayElements

Gets the greatest number of elements one array field update-path traversal may walk through while locating the selected target - independent of MaxArrayElements, which bounds the array being written, not the arrays traversal passes through on the way to it.

public int MaxTraversalArrayElements { get; init; }

Property Value

int

MaxTraversalBytesRead

Gets the greatest total number of bytes update-path traversal may physically read.

public long MaxTraversalBytesRead { get; init; }

Property Value

long

MaxTraversalNestingDepth

Gets the greatest active struct depth update-path traversal may enter.

public int MaxTraversalNestingDepth { get; init; }

Property Value

int

MaxTraversalPointerDepth

Gets the greatest nested pointer depth that update-path traversal may follow.

public int MaxTraversalPointerDepth { get; init; }

Property Value

int

MaxTraversalPointerTargetBytes

Gets the greatest fixed-size target, in bytes, that update-path traversal may reach through one pointer. Variable-length targets are rejected when a value is configured.

public long? MaxTraversalPointerTargetBytes { get; init; }

Property Value

long?

MaxTraversalStringBytes

Gets the greatest encoded-byte length update-path traversal may scan in one terminated string, including its complete terminator.

public long MaxTraversalStringBytes { get; init; }

Property Value

long

RequireExistingPointerTarget

Gets whether an update through .value requires a non-null pointer target.

public bool RequireExistingPointerTarget { get; init; }

Property Value

bool

Methods

Equals(UpdateOptions?)

public bool Equals(UpdateOptions? other)

Parameters

other UpdateOptions

Returns

bool

Equals(WriteOptions?)

public override sealed 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 override bool PrintMembers(StringBuilder builder)

Parameters

builder StringBuilder

Returns

bool

ToString()

public override string ToString()

Returns

string

Operators

operator ==(UpdateOptions?, UpdateOptions?)

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

Parameters

left UpdateOptions

right UpdateOptions

Returns

bool

operator !=(UpdateOptions?, UpdateOptions?)

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

Parameters

left UpdateOptions

right UpdateOptions

Returns

bool