mnx::util::EntityMap Class Reference

Provides type-safe ID-based lookup for elements in an MNX document. More...

#include <EntityMap.h>

Public Member Functions
	EntityMap (std::weak_ptr< json > documentRoot, const std::optional< ErrorHandler > &errorHandler=std::nullopt)
	Constructs the index for a given document.
template<typename T >
std::optional< T >	tryGet (const std::string &id, const std::optional< Base > &errorLocation=std::nullopt) const
	Attempts to look up an object by string ID.
template<typename T >
T	get (const std::string &id, const std::optional< Base > &errorLocation=std::nullopt) const
	Looks up an object by string ID.
template<typename T >
size_t	getIndexOf (const std::string &id, const std::optional< Base > &errorLocation=std::nullopt) const
	Returns the array index of an object identified by ID.
template<typename T >
bool	exists (const std::string &id) const
	Returns whether the specified ID exists in the mapping with type T.
std::optional< part::Beam >	tryGetBeam (const sequence::Event &event) const
	Get the beam for an event, if it is mapped.
std::optional< int >	tryGetBeamStartLevel (const std::string &eventId) const
	Return the secondary beam depth that starts at an event ID, if any.
int	getBeamStartLevel (const std::string &eventId) const
	Return the beam start level for an event ID or 0 if none.
void	clear ()
	Clears all mapped items.
std::optional< int >	tryGetOttavaShift (const sequence::Event &event) const
	Retrieve the ottava shift for an event (if known).
int	getOttavaShift (const sequence::Event &event) const
	Retrieve the ottava shift for an event. Returns 0 if not cached.
const std::vector< std::string > &	getLyricLineOrder () const
	Retrieve the lyric line order.

Friends
class	mnx::Document

Detailed Description

Provides type-safe ID-based lookup for elements in an MNX document.

Constructed from an mnx::Document, the EntityMap scans the document to index all identifiable elements by ID. Supports lookup by type.

Constructor & Destructor Documentation

EntityMap()

mnx::util::EntityMap::EntityMap ( std::weak_ptr< json >  documentRoot, const std::optional< ErrorHandler > &  errorHandler = std::nullopt  )

inlineexplicit

Constructs the index for a given document.

Parameters

documentRoot	Shared pointer to the document's JSON root.
errorHandler	A optional callback function for handling errors.

Member Function Documentation

get()

template<typename T >

T mnx::util::EntityMap::get ( const std::string &  id, const std::optional< Base > &  errorLocation = std::nullopt  ) const

inline

Looks up an object by string ID.

Template Parameters

T	The expected type (e.g., mnx::Part, mnx::Layout, mnx::sequence::Note).

Parameters

id	The ID to search for.
errorLocation	The location in the document for error reporting purposes.

Returns

An instance of T if found.

Exceptions

mapping_error

if the ID is not found.

getIndexOf()

template<typename T >

size_t mnx::util::EntityMap::getIndexOf ( const std::string &  id, const std::optional< Base > &  errorLocation = std::nullopt  ) const

inline

Returns the array index of an object identified by ID.

Looks up an object of type T by its ID and returns the index of that object within its owning array. This is equivalent to calling get<T>() followed by ArrayElementObject::calcArrayIndex().

Template Parameters

T	The expected object type. Must derive from ArrayElementObject.

Parameters

id	The ID of the object to locate.
errorLocation	Optional document location used for error reporting.

Returns

The zero-based array index of the object.

Exceptions

mapping_error

if the ID is not found or does not refer to an object of type T.

tryGet()

template<typename T >

std::optional< T > mnx::util::EntityMap::tryGet ( const std::string &  id, const std::optional< Base > &  errorLocation = std::nullopt  ) const

inline

Attempts to look up an object by string ID.

Template Parameters

T	The expected type (e.g., mnx::Part, mnx::Layout, mnx::sequence::Note).

Parameters

id	The ID to search for.
errorLocation	The location in the document for error reporting purposes.

Returns

An instance of T if found; std::nullopt if the ID is not present.

Exceptions

mapping_error

if the ID is found but has a different type than T (release builds only; debug builds assert instead).

Note

A type mismatch indicates an internal logic error in the ID mapping. This function only models the absence of an ID, not type ambiguity.

tryGetBeam()

std::optional< part::Beam > mnx::util::EntityMap::tryGetBeam ( const sequence::Event &  event ) const

inline

Get the beam for an event, if it is mapped.

Parameters

event

The event to search for.

Returns

The beam or std::nullopt if not found.