Gondwana.TypedValueBag Class Reference

A flexible, strongly-typed value container intended for save-state extensibility. More...

Inheritance diagram for Gondwana.TypedValueBag:

Public Member Functions
	TypedValueBag ()
	Initializes a new instance of the TypedValueBag class using the default JSON serializer settings.
	TypedValueBag (JsonSerializer serializer)
	Initializes a new instance of the TypedValueBag class using a custom JSON serializer.
	TypedValueBag (TypedValueBag other)
	Initializes a new instance of the TypedValueBag class by performing a deep 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.
TypedValueBag	Clone ()
	Creates a deep copy of this TypedValueBag (tokens are cloned).

Detailed Description

A flexible, strongly-typed value container intended for save-state extensibility.

Values are stored internally as JSON tokens keyed by string identifiers, but accessed externally via strongly-typed ValueKey<T> instances to ensure compile-time safety.

This class is designed to be serialized as part of an engine or game save file, while allowing individual projects or modules to attach arbitrary structured data without modifying core engine state.

Constructor & Destructor Documentation

TypedValueBag() [1/3]

Gondwana.TypedValueBag.TypedValueBag

(

)

Initializes a new instance of the TypedValueBag class using the default JSON serializer settings.

TypedValueBag() [2/3]

Gondwana.TypedValueBag.TypedValueBag

(

JsonSerializer

serializer

)

Initializes a new instance of the TypedValueBag class using a custom JSON serializer.

Parameters

serializer

The serializer to use when converting values to and from JSON tokens.

TypedValueBag() [3/3]

Gondwana.TypedValueBag.TypedValueBag

(

TypedValueBag

other

)

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

Parameters

other

The source value bag to copy from.

Exceptions

ArgumentNullException

Thrown if other is null.

All values are cloned at the underlying JSON token level, ensuring that the newly created bag does not share mutable state with the source instance.

This constructor is intended for scenarios such as engine state cloning, snapshot restoration, or asset duplication where isolation between value bags is required.

Member Function Documentation

Clear()

void Gondwana.TypedValueBag.Clear

(

)

Removes all values from the bag.

Clone()

TypedValueBag Gondwana.TypedValueBag.Clone

(

)

Creates a deep copy of this TypedValueBag (tokens are cloned).

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 JSON null.

Returns

The stored value if present; otherwise, defaultValue .

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 are merged at the underlying token level and cloned before insertion, ensuring the two bags do not share mutable state.

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.

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 as JSON null.

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 or the default value of T if the stored value is JSON null.

Returns

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