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

#include <EntityMap.h>

Classes
struct	MappedPosition
	Canonical position value used by EntityMap for measure-relative comparisons and caches. More...

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.

std::optional< MappedPosition >	tryGetEventPosition (const sequence::Event &event) const
	Retrieve the cached mapped position for an event (if known).

MappedPosition	getEventPosition (const sequence::Event &event) const
	Retrieve the cached mapped position for an event.

int	comparePositions (const MappedPosition &lhs, const MappedPosition &rhs, bool rhsIncludesTrailingGrace=false) const
	Compare two mapped positions using global measure order and grace-note targeting.

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

◆ comparePositions()

int mnx::util::EntityMap::comparePositions	(	const MappedPosition &	lhs,
		const MappedPosition &	rhs,
		bool	rhsIncludesTrailingGrace = `false`
	)		const

Compare two mapped positions using global measure order and grace-note targeting.

The inputs may be native MappedPosition values or regular document-backed MeasureRhythmicPosition objects converted implicitly to MappedPosition, provided their measureId values refer to global measure IDs already present in this EntityMap.

Parameters

lhs	The left-hand position to compare.
rhs	The right-hand position to compare.
rhsIncludesTrailingGrace	When true, a right-hand position with `graceIndex == 0` is treated as also including trailing grace notes at the same fractional position, so those grace positions compare equal to `rhs` rather than later than it.

Returns: -1 if lhs is earlier, 1 if later, or 0 if equivalent for the requested policy.

◆ 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.

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ EntityMap()

Member Function Documentation

◆ comparePositions()

◆ get()

◆ getIndexOf()

◆ tryGet()

◆ tryGetBeam()