Infinity::Types::Containers::ImmutableMap Class Reference

Type-safe heterogeneous key-value container for configuration and metadata. More...

#include <ImmutableMap.hpp>

Inheritance diagram for Infinity::Types::Containers::ImmutableMap:

Collaboration diagram for Infinity::Types::Containers::ImmutableMap:

Public Member Functions
	ImmutableMap ()
	Default constructor.
	ImmutableMap (const ImmutableMap &copy)
	Copy constructor.
	ImmutableMap (ImmutableMap &&move)
	Move constructor.
virtual	~ImmutableMap ()
	Destructor.
std::unique_ptr< Core::Base >	clone () const override
virtual const Infinity::Types::TypeID &	typeId () const override
	Gets the TypeID for ImmutableMap.
ImmutableMap &	operator= (const ImmutableMap &copy)
	Copy assignment operator.
ImmutableMap &	operator= (ImmutableMap &&move)
	Move assignment operator.
bool	hasKey (const std::string &key) const
	Checks if a key exists in the map.
bool	hasValueAtKey (const std::string &key) const
	Checks if a key exists and contains a plain value (POD type).
void	set (const std::string &key, std::shared_ptr< const Core::Data > data)
	Sets a key-value pair from a type-erased Data pointer.
template<typename T >
void	set (const std::string &key, const T &data)
	Sets a key-value pair with automatic type wrapping (copy).
template<typename T >
void	set (const std::string &key, T &&data)
	Sets a key-value pair with automatic type wrapping (move).
const Core::Data *	get (const std::string &key) const
	Gets a type-erased pointer to the value at the specified key.
template<typename T >
const T &	get (const std::string &key) const
	Gets a typed reference to the value at the specified key.
template<typename T >
const T &	getValue (const std::string &key) const
	Gets the underlying value from a Value<T> wrapper.
void	clear ()
	Removes all key-value pairs from the map.
size_t	size () const noexcept
	Gets the number of key-value pairs in the map.
Public Member Functions inherited from Infinity::Types::Core::Data
	Data ()
	Data (const Data &other)
	Data (Data &&other)
Data &	operator= (const Data &other)
Data &	operator= (Data &&other)
virtual	~Data ()
	Virtual destructor.
bool	hasProperty (const std::string &key) const
template<typename T >
void	setProperty (const std::string &key, T &&value)
	Sets a typed property value.
template<typename T >
void	setProperty (const std::string &key, const T &value)
	Sets a typed property value.
void	setProperty (const std::string &key, PropertyValue &&value)
	Sets a typed property value.
const PropertyValue &	getProperty (const std::string &key) const
	Gets a property value without type checking.
template<typename T >
const T &	getProperty (const std::string &key) const
	Gets a typed property value.
void	removeProperty (const std::string &key)
Public Member Functions inherited from Infinity::Types::Core::Base
virtual	~Base ()
	Virtual destructor.
virtual std::istream &	legibleDataRead (std::istream &in) override
	Deserializes the object from a single-line text representation.
virtual std::ostream &	legibleDataWrite (std::ostream &out) const override
	Serializes the object to a single-line text representation.

Friends
class	Infinity::IO::Data::ImmutableMapSerializer

Additional Inherited Members
Public Attributes inherited from Infinity::Types::Core::Data
std::unordered_map< std::string, PropertyValue >	properties
	Property storage for arbitrary metadata.

Detailed Description

Type-safe heterogeneous key-value container for configuration and metadata.

ImmutableMap provides a dictionary-like container that stores string-keyed values of heterogeneous types within the Infinity type system. Despite its name, the map is mutable but stores immutable shared pointers to const Data, promoting safe sharing and preventing accidental modification of stored values.

The map automatically handles type wrapping, storing POD types as Value<T> and Data-derived types directly. This makes it ideal for:

• Component configuration parameters
• Metadata and property bags
• Named outputs from procedural systems
• Serializable settings and preferences
• Type-safe data exchange between components

Key features:

• Heterogeneous storage: different value types in the same map
• Type-safe retrieval with automatic unwrapping
• Automatic Value<T> wrapping for POD types
• Full serialization support (read/write/wrap)
• Integration with ProceduralSystem input/output ports
• Move semantics for efficient large object storage

The "immutable" aspect refers to the const-correctness of stored data: values are stored as shared_ptr<const Data>, preventing modification after insertion while allowing safe sharing across the system.

Note

Keys are case-sensitive strings.

Attempting to retrieve a non-existent key throws std::out_of_range.

Use hasKey() to safely check for key existence before retrieval.

Example usage:

// Create and populate a map
ImmutableMap config;
config.set("resolution", 1024);
config.set("scale", 50.0f);
config.set("seed", 12345u);
config.set("name", std::string("TerrainGen"));
 
// Store complex types
Vector3 position{100.0f, 0.0f, 100.0f};
config.set("spawn_point", position);
 
// Retrieve values with type safety
int res = config.get<int>("resolution");
float scale = config.get<float>("scale");
const Vector3& spawn = config.get<Vector3>("spawn_point");
 
// Safe key checking
if (config.hasKey("optional_param")) {
    auto value = config.get<float>("optional_param");
}
 
// Use with ProceduralSystem
system->setIn("config", std::move(config));
 
// Metadata storage
ImmutableMap metadata;
metadata.set("author", std::string("John Doe"));
metadata.set("version", 2);
metadata.set("creation_date", std::string("2025-01-15"));

Constructor & Destructor Documentation

ImmutableMap() [1/3]

Infinity::Types::Containers::ImmutableMap::ImmutableMap

(

)

Default constructor.

Constructs an empty map with no key-value pairs.

ImmutableMap() [2/3]

Infinity::Types::Containers::ImmutableMap::ImmutableMap

(

const ImmutableMap &

copy

)

Copy constructor.

Creates a shallow copy of the map. The underlying shared pointers are copied, so both maps reference the same data objects.

Parameters

copy	Map to copy from.

Note

This is a shallow copy - the data objects themselves are shared.

ImmutableMap() [3/3]

Infinity::Types::Containers::ImmutableMap::ImmutableMap

(

ImmutableMap &&

move

)

Move constructor.

Transfers ownership of the map's contents without copying.

Parameters

move	Map to move from.

~ImmutableMap()

virtual Infinity::Types::Containers::ImmutableMap::~ImmutableMap ( )

virtual

Destructor.

Releases all stored shared pointers. Data objects are destroyed when their reference count reaches zero.

Member Function Documentation

clear()

void Infinity::Types::Containers::ImmutableMap::clear

(

)

Removes all key-value pairs from the map.

Clears the map, releasing all stored shared pointers. Data objects are destroyed if no other references exist.

clone()

std::unique_ptr< Core::Base > Infinity::Types::Containers::ImmutableMap::clone ( ) const

overridevirtual

Reimplemented from Infinity::Types::Core::Data.

get() [1/2]

const Core::Data * Infinity::Types::Containers::ImmutableMap::get

(

const std::string &

key

)

const

Gets a type-erased pointer to the value at the specified key.

Retrieves the raw Data pointer without type-specific unwrapping. Useful when the specific type is unknown or when working generically.

Parameters

key	Key to retrieve.

Returns

Const pointer to the Data object.

Exceptions

std::out_of_range

If key does not exist.

const Core::Data* data = map.get("some_key");
TypeID type = data->typeId();
// Inspect or cast based on type...

get() [2/2]

template<typename T >

const T & Infinity::Types::Containers::ImmutableMap::get ( const std::string &  key ) const

inline

Gets a typed reference to the value at the specified key.

Retrieves and unwraps the value with automatic type checking:

• For Data-derived types: returns the object directly
• For POD types: unwraps from Value<T> and returns the underlying value

Template Parameters

T	Expected type of the value.

Parameters

key	Key to retrieve.

Returns

Const reference to the value.

Exceptions

std::out_of_range	If key does not exist.
std::bad_cast	If the value cannot be cast to type T.

int count = map.get<int>("particle_count");
const Vector3& pos = map.get<Vector3>("position");
float scale = map.get<float>("terrain_scale");

getValue()

template<typename T >

const T & Infinity::Types::Containers::ImmutableMap::getValue ( const std::string &  key ) const

inline

Gets the underlying value from a Value<T> wrapper.

Specialized getter that explicitly unwraps a Value<T> to access the POD value inside. This is useful when you need to be explicit about the Value wrapper type.

Template Parameters

T	Type of the wrapped value.

Parameters

key	Key to retrieve.

Returns

Const reference to the unwrapped value.

Exceptions

std::out_of_range	If key does not exist.
std::bad_cast	If the value is not a Value<T>.

Note

Prefer get<T>() for most use cases, which handles unwrapping automatically.

// Equivalent to get<float>(key)
float scale = map.getValue<float>("scale");

hasKey()

bool Infinity::Types::Containers::ImmutableMap::hasKey

(

const std::string &

key

)

const

Checks if a key exists in the map.

Parameters

key	Key to check for existence.

Returns

True if the key exists, false otherwise.

if (map.hasKey("texture_size")) {
    // Safe to retrieve
    int size = map.get<int>("texture_size");
}

hasValueAtKey()

bool Infinity::Types::Containers::ImmutableMap::hasValueAtKey

(

const std::string &

key

)

const

Checks if a key exists and contains a plain value (POD type).

Returns true if the key exists and its value is a Value<T> wrapper (indicating a POD type like int, float, etc.).

Parameters

key	Key to check.

Returns

True if key exists and contains a Value<T>, false otherwise.

Note

This is distinct from hasKey() - it also checks the value type.

operator=() [1/2]

ImmutableMap & Infinity::Types::Containers::ImmutableMap::operator=

(

const ImmutableMap &

copy

)

Copy assignment operator.

Replaces the map's contents with a shallow copy of another map.

Parameters

copy	Map to copy from.

Returns

Reference to this map.

operator=() [2/2]

ImmutableMap & Infinity::Types::Containers::ImmutableMap::operator=

(

ImmutableMap &&

move

)

Move assignment operator.

Replaces the map's contents by moving from another map.

Parameters

move	Map to move from.

Returns

Reference to this map.

set() [1/3]

template<typename T >

void Infinity::Types::Containers::ImmutableMap::set ( const std::string &  key, const T &  data  )

inline

Sets a key-value pair with automatic type wrapping (copy).

Automatically wraps the value appropriately:

• For Data-derived types: stores directly
• For POD types: wraps in Value<T>

Template Parameters

T	Type of the value to store.

Parameters

key	Key to associate with the value.
data	Value to store (copied).

map.set("count", 42);              // Stored as Value<int>
map.set("scale", 1.5f);            // Stored as Value<float>
Vector3 pos{1, 2, 3};
map.set("position", pos);          // Stored as Vector3 (Data type)

set() [2/3]

void Infinity::Types::Containers::ImmutableMap::set	(	const std::string &	key,
		std::shared_ptr< const Core::Data >	data
	)

Sets a key-value pair from a type-erased Data pointer.

Stores the data directly without additional wrapping. Useful for storing pre-wrapped Data objects or when the type is already erased.

Parameters

key	Key to associate with the data.
data	Shared pointer to const Data to store.

auto data = std::make_shared<Vector3>(1.0f, 2.0f, 3.0f);
map.set("position", data);

set() [3/3]

template<typename T >

void Infinity::Types::Containers::ImmutableMap::set ( const std::string &  key, T &&  data  )

inline

Sets a key-value pair with automatic type wrapping (move).

Automatically wraps the value appropriately using move semantics:

• For Data-derived types: moves directly
• For POD types: wraps in Value<T> with move

Template Parameters

T	Type of the value to store.

Parameters

key	Key to associate with the value.
data	Value to store (moved).

map.set("mesh", std::move(largeMesh));     // Efficient for large objects
map.set("name", std::string("terrain"));   // Moves string

size()

size_t Infinity::Types::Containers::ImmutableMap::size ( ) const

noexcept

Gets the number of key-value pairs in the map.

Returns

Number of entries in the map.

typeId()

virtual const Infinity::Types::TypeID & Infinity::Types::Containers::ImmutableMap::typeId ( ) const

overridevirtual

Gets the TypeID for ImmutableMap.

Returns

TypeID identifying this ImmutableMap type.

Reimplemented from Infinity::Types::Core::Data.

Friends And Related Symbol Documentation

Infinity::IO::Data::ImmutableMapSerializer

friend class Infinity::IO::Data::ImmutableMapSerializer

friend