Gondwana.TypedValueBag Class Reference

A flexible, strongly-typed value container intended for runtime-attached metadata and ephemeral engine state. More...

Inheritance diagram for Gondwana.TypedValueBag:

Public Member Functions
	TypedValueBag ()
	Initializes a new instance of the TypedValueBag class.
	TypedValueBag (TypedValueBag other)
	Initializes a new instance of the TypedValueBag class by performing a copy of another TypedValueBag.
void	Set< T > (ValueKey< T > key, T value)
	Stores a value in the bag under the specified key.
bool	TryGet< T > (ValueKey< T > key, out T? value)
	Attempts to retrieve a value from the bag using the specified key.
T	Get< T > (ValueKey< T > key, T defaultValue=default!)
	Retrieves a value from the bag using the specified key, or returns a default value if the key is not present.
bool	Remove< T > (ValueKey< T > key)
	Removes the value associated with the specified key from the bag.
void	Clear ()
	Removes all values from the bag.
void	MergeFrom (TypedValueBag? incoming, bool overwriteExisting=false)
	Merges values from another TypedValueBag into this instance.
bool	Contains (string keyName)
	Determines whether the bag contains a value for the specified key name, regardless of type.
bool	Contains< T > (ValueKey< T > key)
	Determines whether the bag contains a value for the specified typed key.
TypedValueBag	Clone ()
	Creates a copy of this TypedValueBag.
Dictionary< string, object?>	ToDictionary ()
	Produces a shallow snapshot of the bag's current contents.

Detailed Description

A flexible, strongly-typed value container intended for runtime-attached metadata and ephemeral engine state.

Values are stored internally as plain CLR objects keyed by string identifiers, but they are accessed externally through strongly-typed ValueKey<T> instances. This preserves compile-time safety for callers while avoiding any direct dependency on JSON serialization during ordinary runtime usage.

Unlike a JSON-token-based implementation, this class does not serialize or deserialize values on every set/get operation. It behaves as an in-memory typed bag first, with persistence concerns expected to be handled explicitly at the boundaries of the engine or application.

Values stored in a TypedValueBag are not preserved by JSON serialization. The bag is intended for runtime, transient, or otherwise non-persisted values, and engine-core properties that expose a TypedValueBag should typically be marked with JsonIgnoreAttribute. If an instance of this class is serialized directly, its contents are also intentionally ignored.

Cloning behavior is best-effort:

• If a stored value is null, it remains null.
• If a stored value implements ICloneable, that clone path is used.
• Otherwise, the stored reference is copied as-is (shallow copy).

This means immutable values behave exactly as expected, while mutable reference types can opt into stronger cloning semantics by implementing one of the supported clone contracts.

Definition at line 73 of file TypedValueBag.cs.

Constructor & Destructor Documentation

TypedValueBag() [1/2]

Gondwana.TypedValueBag.TypedValueBag

(

)

Initializes a new instance of the TypedValueBag class.

Definition at line 95 of file TypedValueBag.cs.

TypedValueBag() [2/2]

Gondwana.TypedValueBag.TypedValueBag

(

TypedValueBag

other

)

Initializes a new instance of the TypedValueBag class by performing a copy of another TypedValueBag.

Values are copied using the bag's internal clone strategy. Where possible, mutable values are cloned; where no supported clone mechanism exists, the original reference is reused.

Parameters

other

The source value bag to copy from.

Exceptions

ArgumentNullException

Thrown if other is null.

This constructor is intended for scenarios such as runtime duplication, snapshot creation, undo/redo support, and general engine-state isolation. The exact depth of the copy depends on the clone capabilities of the stored values themselves.

Definition at line 118 of file TypedValueBag.cs.

Member Function Documentation

Clear()

void Gondwana.TypedValueBag.Clear

(

)

Removes all values from the bag.

Definition at line 271 of file TypedValueBag.cs.

Clone()

TypedValueBag Gondwana.TypedValueBag.Clone

(

)

Creates a copy of this TypedValueBag.

The resulting bag is independent at the dictionary level. Individual stored values are duplicated according to the bag's clone strategy.

Returns

A new TypedValueBag instance containing copies of the current entries.

Contains()

bool Gondwana.TypedValueBag.Contains

(

string

keyName

)

Determines whether the bag contains a value for the specified key name, regardless of type.

Parameters

keyName

The logical key name to test.

Returns

true if the bag contains an entry with the specified key name; otherwise, false.

Exceptions

ArgumentException

Thrown if keyName is null, empty, or whitespace.

Definition at line 319 of file TypedValueBag.cs.

Contains< T >()

bool Gondwana.TypedValueBag.Contains< T >

(

ValueKey< T >

key

)

Determines whether the bag contains a value for the specified typed key.

Template Parameters

T	The type associated with the key.

Parameters

key	The strongly-typed key to test.

Returns

true if the bag contains an entry with the specified key name; otherwise, false.

Exceptions

ArgumentException

Thrown if the key name is null, empty, or whitespace.

Definition at line 340 of file TypedValueBag.cs.

Get< T >()

T Gondwana.TypedValueBag.Get< T >	(	ValueKey< T >	key,
		T	defaultValue = default! )

Retrieves a value from the bag using the specified key, or returns a default value if the key is not present.

Template Parameters

T	The expected type of the value.

Parameters

key	The strongly-typed key identifying the value.
defaultValue	The value to return if the key is not found or the stored value is null.

Returns

The stored value if present and non-null; otherwise, defaultValue .

Exceptions

ArgumentException	Thrown if the key name is null, empty, or whitespace.
InvalidCastException	Thrown if a value exists for the specified key but is not compatible with T .

Definition at line 240 of file TypedValueBag.cs.

MergeFrom()

void Gondwana.TypedValueBag.MergeFrom	(	TypedValueBag?	incoming,
		bool	overwriteExisting = false )

Merges values from another TypedValueBag into this instance.

Parameters

incoming	The source bag whose values will be copied into this bag. If null, the method performs no action.
overwriteExisting	If true, values in this bag will be replaced when the same key exists in incoming . If false, existing values are preserved and only missing keys are added.

Values copied from incoming pass through the same clone strategy used by Clone(). This avoids unnecessary sharing where the stored types expose a supported clone mechanism.

Definition at line 293 of file TypedValueBag.cs.

Remove< T >()

bool Gondwana.TypedValueBag.Remove< T >

(

ValueKey< T >

key

)

Removes the value associated with the specified key from the bag.

Template Parameters

T	The type associated with the key.

Parameters

key	The strongly-typed key identifying the value to remove.

Returns

true if the value was found and removed; otherwise, false.

Exceptions

ArgumentException

Thrown if the key name is null, empty, or whitespace.

Definition at line 262 of file TypedValueBag.cs.

Set< T >()

void Gondwana.TypedValueBag.Set< T >	(	ValueKey< T >	key,
		T	value )

Stores a value in the bag under the specified key.

If a value already exists for the given key, it is replaced.

Template Parameters

T	The type of value being stored.

Parameters

key	The strongly-typed key identifying the value.
value	The value to store. A null value is stored explicitly.

Exceptions

ArgumentException

Thrown if the key name is null, empty, or whitespace.

Definition at line 145 of file TypedValueBag.cs.

ToDictionary()

Dictionary< string, object?> Gondwana.TypedValueBag.ToDictionary

(

)

Produces a shallow snapshot of the bag's current contents.

This method is primarily intended for diagnostics, inspection, or external code that wants a plain dictionary view of the stored runtime values.

Returns

A new dictionary containing the current key/value pairs from the bag.

Definition at line 378 of file TypedValueBag.cs.

TryGet< T >()

bool Gondwana.TypedValueBag.TryGet< T >	(	ValueKey< T >	key,
		out T?	value )

Attempts to retrieve a value from the bag using the specified key.

Template Parameters

T	The expected type of the value.

Parameters

key	The strongly-typed key identifying the value.
value	When this method returns true, contains the retrieved value. If the stored value is null, this output receives the default value of T . When the method returns false, this output also receives the default value of T .

Returns

true if a value exists for the specified key; otherwise, false.

Exceptions

ArgumentException	Thrown if the key name is null, empty, or whitespace.
InvalidCastException	Thrown if a value exists for the specified key but is not compatible with T .

This method distinguishes between three cases:

1. No value exists for the key: returns false.
2. A value exists and is null: returns true, with value set to default.
3. A value exists and is non-null: the method verifies type compatibility before returning it.

Definition at line 190 of file TypedValueBag.cs.