musx::dom::EntryInfoPtr::InterpretedIterator Class Reference

Iterator-style wrapper for workaround-aware voice traversal. More...

#include <Entries.h>

Public Member Functions
	InterpretedIterator ()=default
	Default constructor allows null return values by caller.
const EntryInfoPtr &	getEntryInfo () const noexcept
	Returns the entry at the current iterator position.
bool	getEffectiveHidden () const noexcept
	Returns whether the entry should be treated as hidden.
util::Fraction	getEffectiveActualDuration (bool global=false) const
	Return the effective actual duration of the entry. Calling code using InterpretedIterator should use this value rather than the one in the entry.
util::Fraction	getEffectiveElapsedDuration (bool global=false) const
	Return the effective elapsed duration of the entry. Calling code using InterpretedIterator should use this value rather than the one in the entry.
util::Fraction	getEffectiveMeasureStaffDuration () const
	Return the effective measure staff duration of the entry. Calling code using InterpretedIterator should use this value rather than the one in the entry.
bool	calcIsPastLogicalEndOfFrame () const
	Returns true is this entry is past the logical end of the frame, as defined by the length of the measure on the frame's staff.
InterpretedIterator	getNext () const
	Returns an iterator advanced to the next usable entry in this voice.
InterpretedIterator	getPrevious () const
	Returns an iterator advanced to the previous usable entry in this voice.
	operator bool () const noexcept
	Allows the iterator to be used directly in boolean contexts.

Friends
class	EntryFrame
class	EntryInfoPtr

Detailed Description

Iterator-style wrapper for workaround-aware voice traversal.

Beamed-rest workaround

Currently, InterpretedIterator implements only the "beamed-rest workaround". This is the common Finale technique where additional rests are inserted solely to shape beams (for example, to create 16th-note hooks over internal rests by hiding or duplicating rests between voiced layers).

Whenever a position is selected or advanced (including the initial position returned by EntryFrame::getFirstInterpretedIterator), the following rules are applied:

• Hidden voice-1 workaround rests used to enforce a beam shape are returned, and are treated as visible by making getEffectiveHidden return false.
• All other entries are returned with getEffectiveHidden matching their stored isHidden value. isHidden value.

Singleton beam workaround

Handles traversal of beams created by zero-length tuplets. See EntryFrame::TupletInfo::calcCreatesSingletonBeamRight for more information.

If no usable entry exists at or beyond the current position, the iterator evaluates to false in a boolean context and getEntry() returns a null EntryInfoPtr.

Note

Additional workaround families (for example, singleton-beam workarounds or mid-system beam-over-barline workarounds) may be layered onto this iterator in the future without changing its public interface.

InterpretedIterator represents a single position in a voice-1 or voice-2 entry sequence using musxdom's interpretation of Finale user workarounds. It is obtained from EntryFrame::getFirstInterpretedIterator and advanced with InterpretedIterator::getNext().

The iterator encapsulates:

• The target voice (1 or 2).
• The current entry (which may be null if iteration is exhausted).
• An "effective hidden" flag that reflects how the entry should be treated by higher-level consumers after applying workaround rules.
• An "effective actual duration" that provides the actual duration value

Member Function Documentation

getEffectiveActualDuration()

util::Fraction musx::dom::EntryInfoPtr::InterpretedIterator::getEffectiveActualDuration

(

bool

global = false

)

const

Return the effective actual duration of the entry. Calling code using InterpretedIterator should use this value rather than the one in the entry.

Parameters

global

If true, return the global effective actual duration.

getEffectiveElapsedDuration()

util::Fraction musx::dom::EntryInfoPtr::InterpretedIterator::getEffectiveElapsedDuration

(

bool

global = false

)

const

Return the effective elapsed duration of the entry. Calling code using InterpretedIterator should use this value rather than the one in the entry.

Parameters

global

If true, return the global effective elapsed duration.

getEffectiveHidden()

bool musx::dom::EntryInfoPtr::InterpretedIterator::getEffectiveHidden ( ) const

inlinenoexcept

Returns whether the entry should be treated as hidden.

Returns

true if the entry is effectively hidden after applying workaround rules described in the class documentation and false if it is effectively unhidden.

getEntryInfo()

const EntryInfoPtr & musx::dom::EntryInfoPtr::InterpretedIterator::getEntryInfo ( ) const

inlinenoexcept

Returns the entry at the current iterator position.

Returns

A const reference to the underlying EntryInfoPtr (which may be null).

getNext()

EntryInfoPtr::InterpretedIterator musx::dom::EntryInfoPtr::InterpretedIterator::getNext

(

)

const

Returns an iterator advanced to the next usable entry in this voice.

The same workaround rules described in the class documentation are applied when selecting the next position.

Returns

A new InterpretedIterator positioned at the next usable entry, or an empty iterator if no further entry exists.

getPrevious()

EntryInfoPtr::InterpretedIterator musx::dom::EntryInfoPtr::InterpretedIterator::getPrevious

(

)

const

Returns an iterator advanced to the previous usable entry in this voice.

The same workaround rules described in the class documentation are applied when selecting the previous position.

Returns

A new InterpretedIterator positioned at the previous usable entry, or an empty iterator if no further entry exists.

Todo:

Currently m_iteratedEntry is the forward launcher only. However, when we incorporate mid-system beams it will become a backwards launcher as well, and then we will need to differentiate.

operator bool()

musx::dom::EntryInfoPtr::InterpretedIterator::operator bool ( ) const

inlineexplicitnoexcept

Allows the iterator to be used directly in boolean contexts.

Returns

true if the iterator currently refers to a usable entry; false if iteration is exhausted.