A pool that manages collections of OthersBase objects, organized by XML node names and Cmper values. More...

#include <ObjectPool.h>

Classes
struct	ObjectKey
	key type for storing in pool More...

Public Types
using	ObjectPtr = std::shared_ptr< ObjectBaseType >
	shared pointer to `ObjectBaseType`

using	PoolMap = std::map< ObjectKey, ObjectPtr >

Public Member Functions
virtual	~ObjectPool ()=default
	virtual destructor

void	integrityCheckAll () const
	Runs object-local integrity validation for every stored source object.

void	add (ObjectKey key, ObjectPtr object)
	Adds an `ObjectBaseType` object to the pool.

template<typename T >
MusxInstanceList< T >	getArray (const ObjectKey &key, Cmper requestedPartId) const
	Retrieves a vector of objects of a specific type from the pool.

template<typename T >
MusxInstanceList< T >	getArrayForPart (const ObjectKey &key) const
	Retrieves a vector of objects of a specific type from the pool.

template<typename T >
MusxInstance< T >	getSource (const ObjectKey &key) const
	Retrieves the first (and usually only) object of a specific type from the pool.

template<typename T >
std::vector< MusxInstance< T > >	getAllSources (std::optional< Cmper > cmper1=std::nullopt, std::optional< Cmper > cmper2=std::nullopt, std::optional< Inci > inci=std::nullopt) const
	Returns physically stored objects of one type across every source part.

template<typename T >
MusxInstance< T >	getEffectiveSourceForPart (const ObjectKey &key) const
	Retrieves the first (and usually only) object of a specific type from the pool for a part.

template<typename T >
MusxInstance< T >	getEffectiveForPart (const ObjectKey &key) const
	Retrieves the first (and usually only) object of a specific type from the pool for a part.

	ObjectPool (const DocumentWeakPtr &document, const std::unordered_map< std::string_view, dom::EnigmaBase::ShareMode > &knownShareModes={})
	Constructs the object pool.

	ObjectPool (const ObjectPool &other)
	Copies the stored objects without retaining an iterator into the source pool.

ObjectPool &	operator= (const ObjectPool &other)
	Copies the stored objects without retaining an iterator into the source pool.

	ObjectPool (ObjectPool &&)=default

ObjectPool &	operator= (ObjectPool &&)=default

Static Public Member Functions
template<typename T , typename IdGetter >
static std::optional< Cmper >	nextFreeCmper (const MusxInstanceList< T > &items, IdGetter getId)
	Returns the identifier one past the highest currently used in `items`.

Detailed Description

template<typename ObjectBaseType>
class musx::dom::ObjectPool< ObjectBaseType >

A pool that manages collections of OthersBase objects, organized by XML node names and Cmper values.

This class provides functionality to store and retrieve objects derived from a Base object type, It supports dynamic retrieval of objects cast to their specific derived types.

Template Parameters

ObjectBaseType the base type for the objects in the pool

Constructor & Destructor Documentation

◆ ObjectPool()

template<typename ObjectBaseType >

musx::dom::ObjectPool< ObjectBaseType >::ObjectPool	(	const DocumentWeakPtr &	document,
		const std::unordered_map< std::string_view, dom::EnigmaBase::ShareMode > &	knownShareModes = `{}`
	)

inline

Constructs the object pool.

Parameters

document	THe document for this pool.
knownShareModes	Optional parameter that specifies known share modes for certain elements. These can be particurly important for EnigmaBase::ShareMode::None because there may be no parts containing them.

Member Function Documentation

◆ add()

template<typename ObjectBaseType >

void musx::dom::ObjectPool< ObjectBaseType >::add	(	ObjectKey	key,
		ObjectPtr	object
	)

inline

Adds an ObjectBaseType object to the pool.

Parameters

key	The key with which to store the object
object	A shared pointer to the `ObjectBaseType` object to add.

◆ getAllSources()

template<typename ObjectBaseType >

template<typename T >

std::vector< MusxInstance< T > > musx::dom::ObjectPool< ObjectBaseType >::getAllSources	(	std::optional< Cmper >	cmper1 = `std::nullopt`,
		std::optional< Cmper >	cmper2 = `std::nullopt`,
		std::optional< Inci >	inci = `std::nullopt`
	)		const

inline

Returns physically stored objects of one type across every source part.

Parameters

cmper1	If present, restricts the result to this first comparator.
cmper2	If present, restricts the result to this second comparator.
inci	If present, restricts the result to this incidence.

Returns: Source objects in key order, without sharing fallbacks or part-context copies.

◆ getArray()

template<typename ObjectBaseType >

template<typename T >

MusxInstanceList< T > musx::dom::ObjectPool< ObjectBaseType >::getArray	(	const ObjectKey &	key,
		Cmper	requestedPartId
	)		const

inline

Retrieves a vector of objects of a specific type from the pool.

This function may be used to

retrieve a multi-inci array
get all the objects of a specific type, regardless of Cmper value(s), such as getting a vector of all the others::TextExpressionDef instances.

Template Parameters

T	The derived type of `ObjectBaseType` to retrieve.

Parameters

key	The key value used to filter the objects.
requestedPartId	The part for which this array was requested.

Returns: An MusxInstanceList of shared pointers to objects of type T.

◆ getArrayForPart()

template<typename ObjectBaseType >

template<typename T >

MusxInstanceList< T > musx::dom::ObjectPool< ObjectBaseType >::getArrayForPart ( const ObjectKey & key ) const

inline

Retrieves a vector of objects of a specific type from the pool.

This function may be used to

retrieve a multi-inci array
get all the objects of a specific type, regardless of Cmper value(s), such as getting a vector of all the others::TextExpressionDef instances.

Template Parameters

T	The derived type of `ObjectBaseType` to retrieve.

Parameters

key	The key value used to filter the objects.

Returns: An MusxInstanceList of shared pointers to objects of type T.

◆ getEffectiveForPart()

template<typename ObjectBaseType >

template<typename T >

MusxInstance< T > musx::dom::ObjectPool< ObjectBaseType >::getEffectiveForPart ( const ObjectKey & key ) const

inline

Retrieves the first (and usually only) object of a specific type from the pool for a part.

If no part item exists, returns the score item.

If the requestedPartId differs from the sourcePartId, a copy of the source is returned with the requestedPartId set correctly.

Template Parameters

T	The derived type of `OthersBase` to retrieve. Must have a `constexpr static std::string_view XmlNodeName` member.

Parameters

key	The key value used to filter the objects.

Returns: A shared_ptr to the type or nullptr if none exists

◆ getEffectiveSourceForPart()

template<typename ObjectBaseType >

template<typename T >

MusxInstance< T > musx::dom::ObjectPool< ObjectBaseType >::getEffectiveSourceForPart ( const ObjectKey & key ) const

inline

Retrieves the first (and usually only) object of a specific type from the pool for a part.

Warning: The returned value is the source item from the pool and is guaranteed not to be a copy. Because of this, it does not reflect the requested part id. External callers should not directly call this function.

If no part item exists, returns the score item.

Template Parameters

T	The derived type of `OthersBase` to retrieve. Must have a `constexpr static std::string_view XmlNodeName` member.

Parameters

key	The key value used to filter the objects.

Returns: A shared_ptr to the type or nullptr if none exists

◆ getSource()

template<typename ObjectBaseType >

template<typename T >

MusxInstance< T > musx::dom::ObjectPool< ObjectBaseType >::getSource ( const ObjectKey & key ) const

inline

Retrieves the first (and usually only) object of a specific type from the pool.

Warning: The returned value is the source item from the pool and is guaranteed not to be a copy. Because of this, it does not reflect the requested part id. External callers should not directly call this function.

Template Parameters

T	The derived type of `OthersBase` to retrieve. Must have a `constexpr static std::string_view XmlNodeName` member.

Parameters

key	The key value used to filter the objects.

Returns: A shared_ptr to the type or nullptr if none exists

◆ integrityCheckAll()

template<typename ObjectBaseType >

void musx::dom::ObjectPool< ObjectBaseType >::integrityCheckAll ( ) const

inline

Runs object-local integrity validation for every stored source object.

This is called by the document construction finalizer after all overlays are complete.

◆ nextFreeCmper()

template<typename ObjectBaseType >

template<typename T , typename IdGetter >

static std::optional< Cmper > musx::dom::ObjectPool< ObjectBaseType >::nextFreeCmper	(	const MusxInstanceList< T > &	items,
		IdGetter	getId
	)

inlinestatic

Returns the identifier one past the highest currently used in items.

Template Parameters

T	The type stored in `items`.
IdGetter	A callable that returns an item's Cmper identifier.

Parameters

items	The items whose identifiers are being counted.
getId	The callable used to obtain each identifier.

Returns: The next free identifier, or std::nullopt when the identifier space is exhausted.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ObjectPool()

Member Function Documentation

◆ add()

◆ getAllSources()

◆ getArray()

◆ getArrayForPart()

◆ getEffectiveForPart()

◆ getEffectiveSourceForPart()

◆ getSource()

◆ integrityCheckAll()

◆ nextFreeCmper()