Table of Contents

Class UnionValue

Namespace
CStructSharp.Values
Assembly
CStructSharp.dll

Represents the complete storage and overlapping decoded views of a C union without inventing an active member.

public sealed class UnionValue : IDynamicMetaObjectProvider, IReadOnlyDictionary<string, object?>, IReadOnlyCollection<KeyValuePair<string, object?>>, IEnumerable<KeyValuePair<string, object?>>, IEnumerable
Inheritance
UnionValue
Implements
Inherited Members

Examples

UnionValue preserves the complete union storage. You can write those original bytes back or explicitly choose one member as the source for new output:

Both branches in PreserveUnion are compiled and executed by the example runner:

private static void PreserveUnion()
{
    var layout = new CStruct("union choice { uint8 small; uint16 large; };");
    UnionValue parsed = layout.ReadValue<UnionValue>(new byte[] { 0x34, 0x12 }, "choice");
    Equal("choice", parsed.UnionName);
    Equal((ushort)0x1234, (ushort)parsed.Members["large"]!);
    SequenceEqual([0x34, 0x12], layout.Serialize("choice", parsed));

    UnionValue selected = UnionValue.FromMember("choice", "small", (byte)0xA5);
    SequenceEqual([0xA5, 0x00], layout.Serialize("choice", selected));
}

Remarks

Instances are shallowly immutable. Parsed values snapshot the complete raw storage and expose every decoded member view; callers must explicitly select a member before changing what a writer encodes.

Properties

Count

Gets the number of decoded member views.

public int Count { get; }

Property Value

int

HasRawStorage

Gets a value indicating whether this value contains complete raw union storage.

public bool HasRawStorage { get; }

Property Value

bool

HasSelection

Gets a value indicating whether a member was explicitly selected for writing.

public bool HasSelection { get; }

Property Value

bool

this[string]

Gets the decoded view for the exact declared member name.

public object? this[string key] { get; }

Parameters

key string

The case-sensitive declared member name.

Property Value

object

The decoded view, which may be null.

Exceptions

KeyNotFoundException

key has no decoded view.

Keys

Gets the decoded member names in declaration order.

public IEnumerable<string> Keys { get; }

Property Value

IEnumerable<string>

Members

Gets the decoded overlapping member views in declaration order.

public IReadOnlyDictionary<string, object?> Members { get; }

Property Value

IReadOnlyDictionary<string, object>

RawStorage

Gets a defensive view of the complete parsed or explicitly supplied union storage.

public ReadOnlyMemory<byte>? RawStorage { get; }

Property Value

ReadOnlyMemory<byte>?

SelectedMember

Gets the explicitly selected member name, or null for untagged raw storage.

public string? SelectedMember { get; }

Property Value

string

SelectedValue

Gets the explicitly selected member value, including a selected null pointer.

public object? SelectedValue { get; }

Property Value

object

UnionName

Gets the declared union type name.

public string UnionName { get; }

Property Value

string

Values

Gets the decoded member values in declaration order.

public IEnumerable<object?> Values { get; }

Property Value

IEnumerable<object>

Methods

ContainsKey(string)

Returns whether a decoded view exists for the exact member name.

public bool ContainsKey(string key)

Parameters

key string

The case-sensitive declared member name.

Returns

bool

true when a decoded view exists; otherwise, false.

FromMember(string, string, object?)

Creates a new union value with one member explicitly selected for writing.

public static UnionValue FromMember(string unionName, string memberName, object? value)

Parameters

unionName string

The case-sensitive declared union type name.

memberName string

The case-sensitive declared member name to select.

value object

The selected member value, including null for a null pointer member.

Returns

UnionValue

A union value configured to encode memberName.

Exceptions

ArgumentException

unionName is whitespace, or memberName is empty or whitespace.

FromRaw(string, ReadOnlySpan<byte>)

Creates a byte-exact union value without inferring a selected member.

public static UnionValue FromRaw(string unionName, ReadOnlySpan<byte> rawStorage)

Parameters

unionName string

The case-sensitive declared union type name.

rawStorage ReadOnlySpan<byte>

The complete union storage to snapshot.

Returns

UnionValue

A union value configured for byte-exact raw pass-through.

Exceptions

ArgumentException

unionName is whitespace (the empty string names an anonymous union).

GetEnumerator()

Returns an enumerator over decoded member names and values in declaration order.

public IEnumerator<KeyValuePair<string, object?>> GetEnumerator()

Returns

IEnumerator<KeyValuePair<string, object>>

An enumerator over the read-only member snapshot.

GetOrDefault<T>(string, T)

Get<T>(string) with a fallback: fallback when the member is not there, holds null where T cannot, or does not convert; the value otherwise.

public T GetOrDefault<T>(string path, T fallback)

Parameters

path string

The member name or nested path.

fallback T

The value to return when the member cannot be read as T.

Returns

T

The member or fallback.

Type Parameters

T

The requested type.

Get<T>(string)

Reads a member, or a nested value below it, as T with the same checked conversion ReadValue<T> applies - choice.Get<ushort>("wide").

public T Get<T>(string path)

Parameters

path string

A member name, or a dotted and indexed path relative to this union.

Returns

T

The converted value.

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 malformed or selects nothing; the message names the failing segment and the members that exist.

CStructReadException

The value cannot be converted to T without loss.

ToString()

Describes the union for debugging: its name, the selected member when one is set, every decoded member, and the raw storage length when the value carries the bytes as read.

public override string ToString()

Returns

string

A choice { selected: small; small = 52, large = 4660; 2 raw bytes } style rendering.

TryGetValue(string, out object?)

Attempts to get the decoded view for the exact member name.

public bool TryGetValue(string key, out object? value)

Parameters

key string

The case-sensitive declared member name.

value object

Receives the decoded view when found; otherwise, null.

Returns

bool

true when a decoded view exists; otherwise, false.

TryGet<T>(string, out T)

Reads a member, or a nested value below it, as T; returns false instead of throwing when the path selects nothing or the value does not convert.

public bool TryGet<T>(string path, out T value)

Parameters

path string

A member name, or a dotted and indexed path relative to this union.

value T

The converted value, or default when the method returns false.

Returns

bool

true when the path resolved and the value converted.

Type Parameters

T

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

TryGet<T>(string, out T, out CStructException?)

The non-throwing read that says why it failed: failure is the CStructPathException Get<T>(string) raises for a member that is not there or the CStructReadException it raises for a value that does not convert to T, unthrown.

public bool TryGet<T>(string path, out T value, out CStructException? failure)

Parameters

path string

The member name or nested path.

value T

The converted value, or the default when the read failed.

failure CStructException

The failure, or null.

Returns

bool

Whether value holds the member.

Type Parameters

T

The requested type.

WithSelectedMember(string, object?)

Selects one member for writing while retaining any raw snapshot and other decoded views for inspection.

public UnionValue WithSelectedMember(string memberName, object? value)

Parameters

memberName string

The case-sensitive declared member name to select.

value object

The selected member value, including null for a null pointer member.

Returns

UnionValue

A new shallowly immutable union value with the requested selection.

Exceptions

ArgumentException

memberName is empty or whitespace.

WithoutSelection()

Removes an explicit selection and restores raw pass-through behavior.

public UnionValue WithoutSelection()

Returns

UnionValue

A new union value that writes its retained raw storage byte for byte.

Exceptions

InvalidOperationException

This value has no complete raw storage to preserve.

Edit this page