Class StructValue

Namespace

CStructSharp.Values

Assembly

CStructSharp.dll

A parsed struct: the members of one composite in declaration order, readable through dynamic member access (parsed.length), typed through Get<T>(string) (parsed.Get<uint>("length")), through IDictionary<TKey, TValue> / IReadOnlyDictionary<TKey, TValue> (values["length"]), or by enumerating key/value pairs. Members that a conditional arm did not select are absent rather than null. Values are the same objects the documented value table describes (boxed primitives, string, nested StructValue, IList<T> of object for arrays, UnionValue, Pointer, EnumValueResult). Instances are mutable, so a parsed value can be edited and handed back to Serialize/Update.

public sealed class StructValue : IDynamicMetaObjectProvider, IDictionary<string, object?>, ICollection<KeyValuePair<string, object?>>, IReadOnlyDictionary<string, object?>, IReadOnlyCollection<KeyValuePair<string, object?>>, IEnumerable<KeyValuePair<string, object?>>, IEnumerable

Inheritance

object

StructValue

Implements

IDynamicMetaObjectProvider

IDictionary<string, object>

ICollection<KeyValuePair<string, object>>

IReadOnlyDictionary<string, object>

IReadOnlyCollection<KeyValuePair<string, object>>

IEnumerable<KeyValuePair<string, object>>

IEnumerable

Inherited Members

object.GetType()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

StructValue()

Creates an empty value that accepts any member names, for callers assembling data to write.

public StructValue()

Properties

Count

Gets the number of members present.

public int Count { get; }

Property Value

int

this[string]

Gets or sets a member by name; reading an absent member throws KeyNotFoundException.

public object? this[string name] { get; set; }

Parameters

name string

The member name, case-sensitive.

Property Value

object

Keys

Gets the member names in insertion order.

public ICollection<string> Keys { get; }

Property Value

ICollection<string>

Values

Gets the member values in insertion order.

public ICollection<object?> Values { get; }

Property Value

ICollection<object>

Methods

Add(string, object?)

Adds a member; throws when it is already present.

public void Add(string name, object? value)

Parameters

name string

The member name, case-sensitive.

value object

The member value.

Clear()

Removes every member.

public void Clear()

ContainsKey(string)

Returns whether a member is present.

public bool ContainsKey(string name)

Parameters

name string

The member name, case-sensitive.

Returns

bool

true when the member is present.

GetEnumerator()

Enumerates members in insertion order without allocating.

public StructValue.Enumerator GetEnumerator()

Returns

StructValue.Enumerator

A value-type enumerator over the present members.

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: header.Get<ushort>("kind"), packet.Get<byte>("items[2].tag"), record.Get<Point>("origin") for a nested struct mapped to a class or record, node.Get<uint>("next.value.id") through a dereferenced pointer.

public T Get<T>(string path)

Parameters

path string

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

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.

Remove(string)

Removes a member; returns whether it was present.

public bool Remove(string name)

Parameters

name string

The member name, case-sensitive.

Returns

bool

true when the member was present and has been removed.

ToMapped<T>()

Maps this struct to T through its ReadFrom: parsed.ToMapped<Header>().

public T ToMapped<T>() where T : ICStructMapped<T>

Returns

T

The mapped instance.

Type Parameters

T

A class implementing ICStructMapped<TSelf> (hand-written, or generated by [CStructMapped]).

ToString()

Lists the members present, for debugging.

public override string ToString()

Returns

string

A { name = value, … } rendering of the members.

TryGetValue(string, out object?)

Returns the member value, or false when the member is absent.

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

Parameters

name string

The member name, case-sensitive.

value object

The member value when present; otherwise null.

Returns

bool

true when the member is present.

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 struct.

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.