Entries.h

/*
 * Copyright (C) 2025, Robert Patterson
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#pragma once
 
#include <functional>
#include <map>
#include <tuple>
#include <utility>
#include <vector>
 
#include "musx/util/Fraction.h"
#include "BaseClasses.h"
#include "CommonClasses.h"
 // do not add other dom class dependencies. Use Implementations.h for implementations that need total class access.
 
namespace music_theory {
enum class NoteName : int;
class Transposer;
} // namespace music_theory
 
namespace musx {
namespace utils {
enum class PseudoTieMode;
} // namespace utils
 
namespace dom {
 
namespace others {
class Frame;
class PartVoicing;
class PercussionNoteInfo;
class SmartShape;
class Staff;
class StaffComposite;
class StaffUsed;
} // namespace others
 
namespace details {
class TupletDef;
class GFrameHold;
 
class GFrameHoldContext
{
public:
    GFrameHoldContext(const DocumentPtr& document, Cmper partId, Cmper staffId, Cmper measureId, util::Fraction timeOffset = 0);
 
    GFrameHoldContext(const MusxInstance<GFrameHold>& gfHold, util::Fraction timeOffset = 0);
 
    [[nodiscard]]
    Cmper getRequestedPartId() const { return m_requestedPartId; }
 
    [[nodiscard]]
    MusxInstance<others::PartVoicing> getPartVoicing() const { return m_partVoicing; }
 
    [[nodiscard]]
    MusxInstance<others::PartVoicing> getPolicyPartVoicing() const
    { return m_honorPartVoicing ? m_partVoicing : nullptr; }
 
    const GFrameHold* operator->() const { return m_hold.get(); }
 
    explicit operator bool() const noexcept { return static_cast<bool>(m_hold); }
 
    [[nodiscard]]
    ClefIndex calcClefIndexAt(Edu position) const;
 
    [[nodiscard]]
    ClefIndex calcClefIndexAt(util::Fraction position) const
    { return calcClefIndexAt(position.calcEduDuration()); }
 
    [[nodiscard]]
    std::shared_ptr<const EntryFrame> createEntryFrame(LayerIndex layerIndex) const;
 
    bool iterateEntries(LayerIndex layerIndex, std::function<bool(const EntryInfoPtr&)> iterator) const;
 
    bool iterateEntries(std::function<bool(const EntryInfoPtr&)> iterator) const;
 
    [[nodiscard]]
    std::map<LayerIndex, int> calcVoices(bool excludeHidden = false) const;
 
    [[nodiscard]]
    EntryInfoPtr calcNearestEntry(util::Fraction position, bool findExact = true, std::optional<LayerIndex> matchLayer = std::nullopt,
        MatchVoice matchVoice = MatchVoice::Default, util::Fraction atGraceNoteDuration = 0) const;
 
    [[nodiscard]]
    EntryInfoPtr calcNearestEntryAtGraceIndex(util::Fraction position, unsigned graceNoteIndex, bool findExact = true,
        std::optional<LayerIndex> matchLayer = std::nullopt, MatchVoice matchVoice = MatchVoice::Default) const;
 
    util::Fraction snapLocationToEntryOrKeep(util::Fraction location, bool findExact = true) const;
 
    [[nodiscard]]
    util::Fraction calcMinLegacyPickupSpacer() const;
 
    [[nodiscard]]
    bool calcVoicingIncludesLayer(LayerIndex layerIndex) const;
 
    [[nodiscard]]
    bool calcPolicyVoicingIncludesLayer(LayerIndex layerIndex) const
    { return !m_honorPartVoicing || calcVoicingIncludesLayer(layerIndex); }
 
    [[nodiscard]]
    util::Fraction getTimeOffset() const { return m_timeOffset; }
 
private:
    EntryInfoPtr calcNearestEntryMatching(util::Fraction position, bool findExact, std::optional<LayerIndex> matchLayer,
        MatchVoice matchVoice, const std::function<bool(const EntryInfoPtr&)>& matchesEntry) const;
 
    MusxInstance<GFrameHold> m_hold;                    
    Cmper m_requestedPartId{};                          
    util::Fraction m_timeOffset;                        
    MusxInstance<others::PartVoicing> m_partVoicing;    
    bool m_honorPartVoicing{};                          
};
 
} // namespace details
 
Duration calcDurationInfoFromEdu(Edu duration);
 
unsigned calcNumberOfBeamsInEdu(Edu duration);
 
class Note : public EnigmaBase
{
public:
    explicit Note(const DocumentWeakPtr& document, NoteNumber noteId)
        : EnigmaBase(document, 0, ShareMode::All), m_noteId(noteId)
    {
    }
 
    static constexpr NoteNumber RESTID = 31;
 
    struct NoteProperties
    {
        music_theory::NoteName noteName{}; 
        int octave{}; 
        int alteration{}; 
        int staffPosition{}; 
 
        bool operator==(const NoteProperties& other) const
        {
            return noteName == other.noteName && octave == other.octave
                && alteration == other.alteration && staffPosition == other.staffPosition;
        }
 
        bool operator!=(const NoteProperties& other) const
        { return !(*this == other); }
    };
 
    int harmLev{};      
    int harmAlt{};      
    bool isValid{};     
    bool tieStart{};    
    bool tieEnd{};      
    bool crossStaff{};  
    bool upStemSecond{}; 
    bool downStemSecond{}; 
    bool upSplitStem{}; 
    bool showAcci{};    
    bool parenAcci{};   
    bool noPlayback{};  
    bool noSpacing{};   
    bool freezeAcci{};  
    bool playDisabledByHP{}; 
 
    [[nodiscard]]
    NoteNumber getNoteId() const { return m_noteId; }
 
    [[nodiscard]]
    std::pair<int, int> calcDefaultEnharmonic(const MusxInstance<KeySignature>& key) const;
 
    [[nodiscard]]
    NoteProperties calcNoteProperties(const MusxInstance<KeySignature>& key, KeySignature::KeyContext ctx, ClefIndex clefIndex,
        const MusxInstance<others::PercussionNoteInfo>& percNoteInfo, const MusxInstance<others::Staff>& staff = nullptr, bool respellEnharmonic = false) const;
 
    static const xml::XmlElementArray<Note>& xmlMappingArray(); 
 
private:
    NoteNumber m_noteId{}; 
};
 
class Entry : public EnigmaBase
{
public:
    explicit Entry(const DocumentWeakPtr& document, Cmper partId, ShareMode shareMode, EntryNumber entnum, EntryNumber prev, EntryNumber next)
        : EnigmaBase(document, partId, shareMode), m_entnum(entnum), m_prev(prev), m_next(next)
    {
    }
 
    Edu duration{};
    int numNotes{};          
    Evpu hOffsetScore{};     
    bool isValid{};          
    bool isNote{};           
    bool v2Launch{};         
    bool voice2{};           
    bool createdByHP{};      
    bool playDisabledByHP{}; 
    bool graceNote{};        
    bool noteDetail{};       
    bool articDetail{};      
    bool lyricDetail{};      
    bool tupletStart{};      
    bool splitRest{};        
    bool performanceData{};  
    bool floatRest{};        
    bool isHidden{};         
    bool beamExt{};          
    bool flipTie{};          
    bool dotTieAlt{};        
    bool beam{};             
    bool secBeam{};          
    bool freezeStemScore{};  
    bool stemDetail{};       
    bool crossStaff{};       
    bool reverseUpStem{};    
    bool reverseDownStem{};  
    bool doubleStem{};       
    bool splitStem{};        
    bool upStemScore{};      
    bool checkAccis{};       
    bool dummy{};            
    bool smartShapeDetail{}; 
    bool noLeger{};          
    bool sorted{};           
    bool slashGrace{};       
    bool flatBeam{};         
    bool noPlayback{};       
    bool noSpacing{};        
    bool freezeBeam{};       
 
    std::vector<std::shared_ptr<Note>> notes;
 
    struct EntryLocation
    {
        StaffCmper staffId{};       
        MeasCmper measureId{};      
        LayerIndex layerIndex{};    
        size_t entryIndex{};        
 
        bool found() const { return staffId != 0 && measureId != 0; }
        void clear() { *this = {}; }
    } location;                     
 
    [[nodiscard]]
    EntryNumber getEntryNumber() const { return m_entnum; }
 
    [[nodiscard]]
    MusxInstance<Entry> getNext() const;
 
    [[nodiscard]]
    MusxInstance<Entry> getPrevious() const;
 
    [[nodiscard]]
    Duration calcDurationInfo() const { return calcDurationInfoFromEdu(duration); }
 
    [[nodiscard]]
    util::Fraction calcFraction() const { return util::Fraction::fromEdu(duration); }
 
    [[nodiscard]]
    bool hasStem() const { return duration < Edu(NoteType::Whole); }
 
    [[nodiscard]]
    bool isPossibleFullMeasureRest() const
    { return !isNote && !isHidden && duration == Edu(NoteType::Whole); }
 
    void integrityCheck(const std::shared_ptr<EnigmaBase>& ptrToThis) override
    {
        this->EnigmaBase::integrityCheck(ptrToThis);
        if (size_t(numNotes) != notes.size()) {
            MUSX_INTEGRITY_ERROR("Entry " + std::to_string(m_entnum) + " has an incorrect number of notes.");
        }
        // Finale allows both zero-note non-floating rests and even
        // zero-note non-rests, so there is no check against zero notes here.
    }
 
    static void calcLocations(const DocumentPtr& document);
 
    constexpr static std::string_view XmlNodeName = "entry"; 
    static const xml::XmlElementArray<Entry>& xmlMappingArray(); 
 
private:
    EntryNumber m_entnum{}; 
    EntryNumber m_prev{};   
    EntryNumber m_next{};   
};
 
class EntryInfo;
class EntryFrame;
class NoteInfoPtr;
 
struct StaffPositionPitchOptions
{
    PitchMode pitchMode{ PitchMode::CurrentView }; 
    std::optional<int> actualAlteration{}; 
};
 
struct NotePropertiesOptions
{
    PitchMode pitchMode{ PitchMode::CurrentView }; 
    EnharmonicOverride enharmonicOverride{ EnharmonicOverride::None }; 
    bool alwaysUseEntryStaff{}; 
};
 
class EntryInfoPtr
{
public:
    enum class BeamIterationMode
    {
        Normal,             
        IncludeAll,         
        Interpreted         
    };
 
    class InterpretedIterator;
 
    EntryInfoPtr() : m_entryFrame(nullptr), m_indexInFrame(0) {}
 
    explicit EntryInfoPtr(const std::shared_ptr<const EntryFrame>& entryFrame, size_t index = 0)
        : m_entryFrame(entryFrame), m_indexInFrame(index) {}
 
    [[nodiscard]]
    static EntryInfoPtr fromEntryNumber(const DocumentPtr& document, Cmper partId, EntryNumber entryNumber, util::Fraction timeOffset = 0);
 
    const std::shared_ptr<const EntryInfo> operator->() const;
 
    operator bool() const noexcept;
 
    [[nodiscard]] int getVoice() const;
 
    [[nodiscard]] bool isSameEntry(const EntryInfoPtr& src) const;
 
    [[nodiscard]] bool calcIsSamePitchContent(const EntryInfoPtr& src, bool compareConcert = true) const;
 
    [[nodiscard]]
    bool calcIsSamePitchContentAndDuration(const EntryInfoPtr& src, bool compareConcert = true, bool requireSameVoice = true, bool requireSameGraceElapsedDura = false) const;
 
    [[nodiscard]]
    bool calcContainsPitchContent(const EntryInfoPtr& src, bool compareConcert = true) const;
 
    [[nodiscard]]
    NoteInfoPtr findNoteId(NoteNumber noteId) const;
 
    [[nodiscard]] std::shared_ptr<const EntryFrame> getFrame() const { return m_entryFrame; }
 
    [[nodiscard]] size_t getIndexInFrame() const { return m_indexInFrame; }
 
    [[nodiscard]] LayerIndex getLayerIndex() const;
 
    [[nodiscard]] StaffCmper getStaff() const;
 
    [[nodiscard]] MusxInstance<others::StaffComposite> createCurrentStaff(const std::optional<StaffCmper>& forStaffId = std::nullopt) const;
 
    [[nodiscard]] MeasCmper getMeasure() const;
 
    [[nodiscard]] MusxInstance<KeySignature> getKeySignature() const;
 
    [[nodiscard]]
    music_theory::Pitch calcPitchFromStaffPosition(int staffPosition, StaffPositionPitchOptions options = {}) const;
 
    [[nodiscard]] MusxInstance<details::EntryPartFieldDetail> getPartFieldData() const;
 
    [[nodiscard]] Evpu calcManuaOffset() const;
 
    [[nodiscard]] unsigned calcReverseGraceIndex() const;
 
    [[nodiscard]] util::Fraction calcGraceElapsedDuration() const;
 
    [[nodiscard]] std::optional<size_t> calcNextTupletIndex(std::optional<size_t> currentIndex = 0) const;
 
    [[nodiscard]] EntryInfoPtr getNextInFrame() const;
 
    [[nodiscard]] EntryInfoPtr getNextInLayer(std::optional<MeasCmper> targetMeasure = std::nullopt) const;
 
    [[nodiscard]] EntryInfoPtr getNextSameV() const;
 
    [[nodiscard]] EntryInfoPtr getNextSameVNoGrace() const;
 
    [[nodiscard]] EntryInfoPtr getPreviousInLayer(std::optional<MeasCmper> targetMeasure = std::nullopt) const;
 
    [[nodiscard]] EntryInfoPtr getPreviousInFrame() const;
 
    [[nodiscard]] EntryInfoPtr getPreviousSameV() const;
 
    [[nodiscard]] EntryInfoPtr getPreviousSameVNoGrace() const;
 
    [[nodiscard]] EntryInfoPtr getNextInVoice(int voice) const;
 
    [[nodiscard]] EntryInfoPtr getPreviousInVoice(int voice) const;
 
    [[nodiscard]] InterpretedIterator asInterpretedIterator(bool remapBeamOverBarlineEntries = true) const;
 
    [[nodiscard]]
    EntryInfoPtr getNextInBeamGroup(BeamIterationMode beamIterationMode = BeamIterationMode::Normal) const
    { return iterateBeamGroup<&EntryInfoPtr::nextPotentialInBeam, &EntryInfoPtr::previousPotentialInBeam>(beamIterationMode); }
 
    [[nodiscard]]
    EntryInfoPtr getPreviousInBeamGroup(BeamIterationMode beamIterationMode = BeamIterationMode::Normal) const
    { return iterateBeamGroup<&EntryInfoPtr::previousPotentialInBeam, &EntryInfoPtr::nextPotentialInBeam>(beamIterationMode); }
 
    [[nodiscard]] EntryInfoPtr getNextInBeamGroupAcrossBars(BeamIterationMode beamIterationMode = BeamIterationMode::Normal) const;
 
    [[nodiscard]] EntryInfoPtr getPreviousInBeamGroupAcrossBars(BeamIterationMode beamIterationMode = BeamIterationMode::Normal) const;
 
    [[nodiscard]] bool calcDisplaysAsRest() const;
 
    [[nodiscard]] std::pair<int, int> calcTopBottomStaffPositions() const;
 
    [[nodiscard]] int calcZeroNotePosition() const;
 
    [[nodiscard]] std::pair<Evpu, Evpu> calcTopBottomExtent() const;
 
    [[nodiscard]] std::pair<bool, bool> calcEntryStemSettings() const;
 
    [[nodiscard]] bool calcUpStemDefault() const;
 
    [[nodiscard]] StemDirection calcStemDirectionForced() const;
 
    [[nodiscard]] bool calcUpStem() const
    {
        if (m_upStem.has_value()) {
            return m_upStem.value();
        }
        m_upStem = calcUpStemImpl();
        return m_upStem.value();
    }
 
    [[nodiscard]] bool calcGraceNoteSlash(const MusxInstance<options::GraceNoteOptions> graceOptions = nullptr) const;
 
    [[nodiscard]] bool calcUnbeamed() const;
 
    [[nodiscard]] bool calcIsBeamStart(BeamIterationMode beamIterationMode = BeamIterationMode::Normal) const;
 
    [[nodiscard]] bool calcCreatesSingletonBeamLeft() const;
 
    [[nodiscard]] bool calcCreatesSingletonBeamRight() const;
 
    [[nodiscard]] EntryInfoPtr calcBeamContinuesLeftOverBarline() const;
 
    [[nodiscard]] EntryInfoPtr calcBeamContinuesRightOverBarline() const;
 
    [[nodiscard]] bool calcIsFeatheredBeamStart(Evpu& outLeftY, Evpu& outRightY) const;
 
    [[nodiscard]] EntryInfoPtr findBeamStartOrCurrent() const;
 
    [[nodiscard]] EntryInfoPtr findBeamEnd() const;
 
    [[nodiscard]] unsigned calcNumberOfBeams() const;
 
    [[nodiscard]] unsigned calcLowestBeamStart(bool considerBeamOverBarlines = false) const;
 
    [[nodiscard]] unsigned calcLowestBeamEnd() const;
 
    [[nodiscard]] unsigned calcLowestBeamEndAcrossBarlines() const;
 
    [[nodiscard]] unsigned calcLowestBeamStub() const;
 
    [[nodiscard]] bool calcBeamStubIsLeft() const;
 
    [[nodiscard]] util::Fraction calcGlobalElapsedDuration() const;
 
    [[nodiscard]] util::Fraction calcGlobalActualDuration() const;
 
    [[nodiscard]]
    bool calcIsImmediatelyFollowedBy(const EntryInfoPtr& nextEntry) const;
 
    [[nodiscard]] bool calcCanBeBeamed() const;
 
    [[nodiscard]] bool calcBeamMustStartHere() const;
 
    [[nodiscard]] int calcEntrySize() const;
 
    [[nodiscard]] bool calcIsFullMeasureRest() const;
 
    [[nodiscard]] bool calcIsBeamedRestWorkaroundHiddenRest() const;
 
    [[nodiscard]] bool calcIsBeamedRestWorkaroundVisibleRest() const;
 
    [[nodiscard]] std::vector<size_t> findTupletInfo() const;
 
    [[nodiscard]] bool calcIfLayerSettingsApply() const;
 
    [[nodiscard]] int calcCrossStaffDirectionForAll(DeferredReference<MusxInstanceList<others::StaffUsed>> staffList = {}) const;
 
    [[nodiscard]] std::optional<StaffCmper> calcCrossedStaffForAll() const;
 
    [[nodiscard]] bool calcIsSingletonGrace() const;
 
    [[nodiscard]] bool calcHasGraceNote() const;
 
    [[nodiscard]] int calcIsAuxiliaryPitchMarker() const;
 
    [[nodiscard]] bool calcIsTrillToGraceEntry() const;
 
    [[nodiscard]] bool calcIsGlissToGraceEntry() const;
 
    [[nodiscard]] EntryInfoPtr findHiddenSourceForBeamOverBarline() const;
 
    [[nodiscard]] EntryInfoPtr findDisplayEntryForBeamOverBarline() const;
 
    [[nodiscard]] EntryInfoPtr findMainEntryForGraceNote(bool ignoreRests = false) const;
 
    bool iterateStartingSmartShapes(std::function<bool(const MusxInstance<others::SmartShape>&)> callback, bool findExact = false) const;
 
    bool operator<(const EntryInfoPtr& other) const
    {
        if (m_entryFrame != other.m_entryFrame)
            return m_entryFrame < other.m_entryFrame;
        return m_indexInFrame < other.m_indexInFrame;
    }
 
private:
    [[nodiscard]] unsigned calcVisibleBeams() const;
 
    [[nodiscard]] bool calcUpStemImpl() const;
 
    template<EntryInfoPtr(EntryInfoPtr::* Iterator)() const>
    [[nodiscard]] std::optional<unsigned> iterateFindRestsInSecondaryBeam(const EntryInfoPtr nextOrPrevInBeam) const;
 
    template<EntryInfoPtr(EntryInfoPtr::* Iterator)() const>
    [[nodiscard]] EntryInfoPtr iteratePotentialEntryInBeam() const;
 
    template<EntryInfoPtr(EntryInfoPtr::* Iterator)() const>
    [[nodiscard]] bool iterateNotesExistLeftOrRight() const;
 
    [[nodiscard]] EntryInfoPtr nextPotentialInBeam(BeamIterationMode beamIterationMode) const;
 
    [[nodiscard]] EntryInfoPtr previousPotentialInBeam(BeamIterationMode beamIterationMode) const;
 
    using BeamIteratorFn = EntryInfoPtr (EntryInfoPtr::*)(BeamIterationMode) const;
    template<BeamIteratorFn Iterator, BeamIteratorFn ReverseIterator>
    [[nodiscard]] EntryInfoPtr iterateBeamGroup(BeamIterationMode beamIterationMode) const;
 
    [[nodiscard]] EntryInfoPtr findLeftBeamAnchorForBeamOverBarline() const;
 
    [[nodiscard]] EntryInfoPtr findRightBeamAnchorForBeamOverBarline() const;
 
    std::shared_ptr<const EntryFrame> m_entryFrame;
    size_t m_indexInFrame{};              
 
    mutable MusxInstance<others::StaffComposite> m_cachedStaff;
 
    mutable std::optional<bool> m_upStem;
};
 
//    the the caller should use for calculating elapsed time.
class EntryInfoPtr::InterpretedIterator
{
    EntryInfoPtr m_entry;                       
    bool m_effectiveHidden{};                   
    // --------
    // internal
    // --------
    EntryInfoPtr m_iteratedEntry;               
    bool m_useIteratedForBackLaunch{};          
    bool m_remapBeamOverBarlineEntries{};       
 
    [[nodiscard]] const EntryInfoPtr& getIteratedEntry() const noexcept
    { return m_iteratedEntry ? m_iteratedEntry : m_entry; }
 
    [[nodiscard]] const EntryInfoPtr& getForwardLaunchEntry() const noexcept
    { return getIteratedEntry(); }
 
    [[nodiscard]] const EntryInfoPtr& getBackwardLaunchEntry() const noexcept
    { return m_useIteratedForBackLaunch ? getIteratedEntry() : m_entry; }
 
    InterpretedIterator(EntryInfoPtr entry, bool remapBeamOverBarlineEntries);
 
    friend class EntryFrame;
    friend class EntryInfoPtr;
 
public:
    InterpretedIterator() = default;
 
    [[nodiscard]] const EntryInfoPtr& getEntryInfo() const noexcept { return m_entry; }
 
    [[nodiscard]] bool getEffectiveHidden() const noexcept { return m_effectiveHidden; }
 
    [[nodiscard]] util::Fraction getEffectiveActualDuration(bool global = false) const;
 
    [[nodiscard]] util::Fraction getEffectiveElapsedDuration(bool global = false) const;
 
    [[nodiscard]] util::Fraction getEffectiveMeasureStaffDuration() const;
 
    [[nodiscard]] bool calcIsPastLogicalEndOfFrame() const;
 
    [[nodiscard]] InterpretedIterator getNext() const;
 
    [[nodiscard]] InterpretedIterator getPrevious() const;
 
    explicit operator bool() const noexcept
    {
        return static_cast<bool>(m_entry);
    }
};
 
class EntryFrame : public std::enable_shared_from_this<EntryFrame>
{
public:
    explicit EntryFrame(const details::GFrameHoldContext& gfhold, LayerIndex layerIndex, util::Fraction timeStretch, const MusxInstance<others::StaffComposite>& startStaff) :
        m_context(gfhold),
        m_layerIndex(layerIndex),
        m_timeStretch(timeStretch),
        m_startStaff(startStaff)
    {
    }
 
    struct TupletInfo
    {
        MusxInstance<details::TupletDef> tuplet;  
        size_t startIndex;                              
        size_t endIndex;                                
        util::Fraction startDura;                       
        util::Fraction endDura;                         
        bool voice2;                                    
 
        TupletInfo(const std::weak_ptr<const EntryFrame>& parent, const MusxInstance<details::TupletDef>& tup, size_t index, util::Fraction start, bool forVoice2)
            : tuplet(tup), startIndex(index), endIndex((std::numeric_limits<size_t>::max)()),
                startDura(start), endDura(-1), voice2(forVoice2), m_parent(parent)
        {}
 
        [[nodiscard]]
        size_t numEntries() const
        {
            MUSX_ASSERT_IF(startIndex > endIndex) {
                throw std::logic_error("TupletInfo has invalid start and end indices.");
            }
            return endIndex - startIndex + 1;
        }
 
        [[nodiscard]]
        bool includesEntry(const EntryInfoPtr& entryInfo) const
        {
            const size_t x = entryInfo.getIndexInFrame();
            return (x >= startIndex && x <= endIndex);
        }
 
        [[nodiscard]]
        bool calcIsTremolo() const;
 
        [[nodiscard]]
        bool calcCreatesSingletonBeamRight() const { return calcCreatesSingleton(false); }
 
        [[nodiscard]]
        bool calcCreatesSingletonBeamLeft() const { return calcCreatesSingleton(true); }
 
        //      - the independent display time signature matches the tuplet's total display duration
        [[nodiscard]]
        bool calcCreatesTimeStretch() const;
 
    private:
        [[nodiscard]]
        bool calcCreatesSingleton(bool left) const;
 
        [[nodiscard]]
        const std::shared_ptr<const EntryFrame> getParent() const
        {
            auto result = m_parent.lock();
            MUSX_ASSERT_IF(!result) {
                throw std::logic_error("Unable to obtain lock on parent entry frame.");
            }
            return result;
        }
 
        const std::weak_ptr<const EntryFrame> m_parent;
    };
 
    std::vector<TupletInfo> tupletInfo;
    MusxInstance<KeySignature> keySignature;    
    util::Fraction measureStaffDuration;        
    util::Fraction maxElapsedStaffDuration;     
 
    [[nodiscard]]
    DocumentPtr getDocument() const;
 
    [[nodiscard]]
    const details::GFrameHoldContext& getContext() const { return m_context; }
 
    [[nodiscard]]
    Cmper getRequestedPartId() const { return m_context.getRequestedPartId(); }
 
    [[nodiscard]]
    StaffCmper getStaff() const;
 
    [[nodiscard]]
    MeasCmper getMeasure() const;
 
    [[nodiscard]]
    LayerIndex getLayerIndex() const { return m_layerIndex; }
 
    [[nodiscard]]
    MusxInstance<others::LayerAttributes> getLayerAttributes() const;
 
    [[nodiscard]]
    util::Fraction getTimeStretch() const { return m_timeStretch; }
 
    [[nodiscard]]
    const std::vector<std::shared_ptr<const EntryInfo>>& getEntries() const
    { return m_entries; }
 
    [[nodiscard]]
    EntryInfoPtr getFirstInVoice(int voice) const;
 
    [[nodiscard]]
    EntryInfoPtr getLastInVoice(int voice) const;
 
    [[nodiscard]]
    EntryInfoPtr::InterpretedIterator getFirstInterpretedIterator(int voice, bool remapBeamOverBarlineEntries = true) const;
 
    void addEntry(const std::shared_ptr<const EntryInfo>& entry)
    { m_entries.emplace_back(entry); }
 
    [[nodiscard]]
    std::shared_ptr<const EntryFrame> getNext(std::optional<MeasCmper> targetMeasure = std::nullopt) const;
 
    [[nodiscard]]
    std::shared_ptr<const EntryFrame> getPrevious(std::optional<MeasCmper> targetMeasure = std::nullopt) const;
 
    [[nodiscard]]
    MusxInstance<others::StaffComposite> getStartStaffInstance() const
    { return m_startStaff; }
 
    [[nodiscard]]
    MusxInstance<others::StaffComposite> createCurrentStaff(Edu eduPosition, const std::optional<StaffCmper>& forStaffId = std::nullopt) const;
 
    [[nodiscard]]
    MusxInstance<others::Measure> getMeasureInstance() const;
 
    [[nodiscard]]
    bool calcAreAllEntriesHiddenInFrame() const;
 
    [[nodiscard]]
    EntryInfoPtr calcNearestEntry(util::Fraction position, bool findExact = true, MatchVoice matchVoice = MatchVoice::Default,
        util::Fraction atGraceNoteDuration = 0) const;
 
    bool iterateEntries(std::function<bool(const EntryInfoPtr&)> iterator) const;
 
private:
    details::GFrameHoldContext m_context;
    LayerIndex m_layerIndex;
    util::Fraction m_timeStretch;
 
    std::vector<std::shared_ptr<const EntryInfo>> m_entries;
 
    MusxInstance<others::StaffComposite> m_startStaff;
 
    mutable MusxInstance<others::LayerAttributes> m_cachedLayerAttributes;
};
 
namespace details {
class GFrameHold;
} // namespace details
 
class EntryInfo
{
    explicit EntryInfo(const MusxInstance<Entry>& entry)
        : m_entry(entry) {}
 
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
    friend details::GFrameHoldContext;
#endif
 
public:
    util::Fraction elapsedDuration{};   
    util::Fraction actualDuration{};    
    util::Fraction cumulativeRatio{};   
    unsigned graceIndex{};              
    ClefIndex clefIndex{};              
    ClefIndex clefIndexConcert{};       
 
    [[nodiscard]]
    MusxInstance<Entry> getEntry() const
    {
        auto retval = m_entry.lock();
        if (!retval) {
            throw std::logic_error("Entry pointer is no longer valid");
        }
        return retval;
    }
 
    [[nodiscard]]
    util::Fraction calcNextElapsedDuration() const
    { return elapsedDuration + actualDuration; }
 
private:
    MusxInstanceWeak<Entry> m_entry;
};
 
class NoteInfoPtr
{
public:
    NoteInfoPtr() : m_entry(), m_noteIndex(0) {}
 
    NoteInfoPtr(const EntryInfoPtr& entryInfo, size_t noteIndex)
        : m_entry(entryInfo), m_noteIndex(noteIndex)
    {}
 
    explicit operator bool() const noexcept
    { return m_entry && m_noteIndex < m_entry->getEntry()->notes.size(); }
 
    [[nodiscard]]
    bool isSameNote(const NoteInfoPtr& src) const
    { return m_entry.isSameEntry(src.m_entry) && m_noteIndex == src.m_noteIndex; }
 
    [[nodiscard]]
    NoteInfoPtr findEqualPitch(const EntryInfoPtr& entry) const;
 
    [[nodiscard]]
    MusxInstance<Note> operator->() const
    {
        MUSX_ASSERT_IF(m_noteIndex >= m_entry->getEntry()->notes.size()) {
            throw std::logic_error("Note index is too large for notes array.");
        }
        return m_entry->getEntry()->notes[m_noteIndex];
    }
 
    [[nodiscard]]
    EntryInfoPtr getEntryInfo() const
    { return m_entry; }
 
    [[nodiscard]]
    size_t getNoteIndex() const
    { return m_noteIndex; }
 
    [[nodiscard]]
    Note::NoteProperties calcNoteProperties(NotePropertiesOptions options = {}) const;
 
    [[nodiscard]]
    MusxInstance<others::PercussionNoteInfo> calcPercussionNoteInfo() const;
 
    struct NoteheadInfo
    {
        MusxInstance<FontInfo> font;   
        char32_t character{};          
        int percent{100};              
        Evpu horzOffset{};              
        Evpu vertOffset{};              
    };
 
    [[nodiscard]]
    NoteheadInfo calcNoteheadInfo() const;
 
    [[nodiscard]]
    NoteInfoPtr calcTieTo() const;
 
    [[nodiscard]]
    NoteInfoPtr calcTieFrom(bool requireTie = true) const;
 
    [[nodiscard]]
    CurveContourDirection calcFreezeTieDirection(bool forTieEnd = false) const;
 
    [[nodiscard]]
    CurveContourDirection calcEffectiveTieDirection(bool forTieEnd = false) const;
    [[nodiscard]] bool calcHasOuterTie(bool forTieEnd = false) const;
 
    [[nodiscard]] bool calcHasInnerTie(bool forTieEnd = false) const;
 
    [[nodiscard]]
    StaffCmper calcStaff() const;
 
    [[nodiscard]]
    std::unique_ptr<music_theory::Transposer> createTransposer() const;
 
    [[nodiscard]]
    NoteInfoPtr getNext() const
    {
        if (m_noteIndex >= m_entry->getEntry()->notes.size()) {
            return NoteInfoPtr();
        }
        return NoteInfoPtr(m_entry, m_noteIndex + 1);
    }
 
    [[nodiscard]]
    NoteInfoPtr getPrevious() const
    {
        if (m_noteIndex <= 0) {
            return NoteInfoPtr();
        }
        return NoteInfoPtr(m_entry, m_noteIndex - 1);
    }
 
    [[nodiscard]]
    bool calcIsEnharmonicRespell() const;
 
    [[nodiscard]]
    std::pair<int, int> calcDefaultEnharmonic() const
    { return (*this)->calcDefaultEnharmonic(m_entry.getKeySignature()); }
 
    [[nodiscard]]
    bool calcIsEnharmonicRespellInAnyPart() const;
 
    [[nodiscard]]
    int calcCrossStaffDirection(DeferredReference<MusxInstanceList<others::StaffUsed>> staffList = {}) const;
 
    [[nodiscard]]
    bool calcIsIncludedInVoicing() const;
 
    [[nodiscard]]
    bool calcIsTop() const;
 
    [[nodiscard]]
    bool calcIsBottom() const;
 
    struct TieStandInSource
    {
        enum class Type
        {
            SmartShape,         
            ShapeExpression,    
            ShapeArticulation,  
        };
 
        Type type{ Type::SmartShape };                             
        Cmper sourceId{};                                          
        std::optional<Inci> sourceInci{};                          
        CurveContourDirection direction{ CurveContourDirection::Unspecified }; 
    };
 
    struct ArpeggiatedTieInfo
    {
        EntryInfoPtr targetEntry{};                                
        size_t targetNoteIndex{};                                  
        CurveContourDirection direction{ CurveContourDirection::Unspecified }; 
        Cmper smartShapeId{};                                      
    };
 
    struct PseudoTieInfo
    {
        bool matched{};                                            
        CurveContourDirection direction{ CurveContourDirection::Unspecified }; 
        std::vector<TieStandInSource> sources{};                   
 
        explicit operator bool() const noexcept { return matched; }
    };
 
    [[nodiscard]]
    std::optional<ArpeggiatedTieInfo> calcArpeggiatedTieInfo() const;
 
    [[nodiscard]]
    PseudoTieInfo calcPseudoLvTieInfo() const;
 
    [[nodiscard]]
    PseudoTieInfo calcPseudoTieEndInfo() const;
 
    [[nodiscard]]
    std::vector<std::pair<NoteInfoPtr, CurveContourDirection>> calcJumpTieContinuationsFrom() const;
 
private:
    enum class TieFromSearchAction {
        Continue,
        Accept,
        Stop,
    };
 
    static NoteInfoPtr findTieFromCandidate(const NoteInfoPtr& note, Cmper previousMeasure,
        const std::function<TieFromSearchAction(const NoteInfoPtr&, bool)>& decide);
 
    [[nodiscard]]
    PseudoTieInfo calcPseudoTieInfoInternal(utils::PseudoTieMode mode) const;
 
    [[nodiscard]]
    bool selectPseudoTieDirectionAndMatch(PseudoTieInfo* info,
        std::vector<CurveContourDirection>& directions,
        const std::vector<size_t>* eligibleNoteIndices = nullptr) const;
 
    [[nodiscard]]
    bool isSamePitch(const NoteInfoPtr& src) const;
 
    [[nodiscard]]
    bool isSamePitchValues(const NoteInfoPtr& src) const;
 
    [[nodiscard]]
    NoteInfoPtr calcTieToWithNextMeasure(Cmper nextMeasure) const;
 
    [[nodiscard]]
    NoteInfoPtr calcTieFromWithPreviousMeasure(Cmper previousMeasure, bool requireTie) const;
 
    EntryInfoPtr m_entry;
    size_t m_noteIndex;
 
    mutable std::optional<CurveContourDirection> m_tieDirection{};
};
 
} // namespace dom
} // namespace entries