Location.h

//  trax track library
//  AD 2013 
//
//  "Sooner or later in life
//   the things you love you'll loose"
//
//              Florence + The Machine
//
// Copyright (c) 2025 Trend Redaktions- und Verlagsgesellschaft mbH
// Copyright (c) 2019 Marc-Michael Horstmann
//
// Permission is hereby granted to any person obtaining a copy of this software 
// and associated source code (the "Software"), to use, view, and study the 
// Software for personal or internal business purposes, subject to the following 
// conditions:
//
// 1. Redistribution, modification, sublicensing, or commercial use of the 
// Software is NOT permitted without prior written consent from the copyright 
// holder.
//
// 2. The Software is provided "AS IS", without warranty of any kind, express 
// or implied.
//
// 3. All copies of the Software must retain this license notice.
//
// For further information, please contact: horstmann.marc@trendverlag.de
 
#pragma once

 
#include "Units.h"
#include "Track.h"
#include "TrackLocation.h"
 
#include <memory>
 
namespace trax
{
    struct Event;
    struct SignalTarget;
 
    struct TrackLocation;
    template<typename> struct TrackData;

    class Location{
    public:
        dclspc Location() noexcept = default;
        dclspc Location( const Location& location ) noexcept = default;
        dclspc Location( Location&& location ) noexcept = default;
        dclspc Location( std::shared_ptr<const Track> pTrack, const TrackLocation& tl );
        dclspc Location( const Track& track, const TrackLocation& tl );
 
        dclspc virtual ~Location() = default;

        dclspc Location& operator=( const Location& location ) noexcept = default;
        dclspc Location& operator=( Location&& location ) noexcept = default;
 

        dclspc void PutOn( std::shared_ptr<const Track> pTrack, const TrackLocation& tl );
 

        dclspc void PutOff() noexcept;
 

        dclspc bool IsOnTrack() const noexcept;
 

        dclspc std::shared_ptr<const Track> GetTrack() const noexcept;
 

        dclspc Length Param() const noexcept;
 

        dclspc Orientation Orient() const noexcept;
 

        dclspc AnglePerLength Curvature() const;
 

        dclspc AnglePerLength Torsion() const;
 

        dclspc void TNBFrame( spat::Frame<Length,One>& frame ) const;
 

        dclspc void Get( TrackLocation& tl ) const noexcept;
 

        dclspc void Get( TrackLocationRef& tlr ) const noexcept;
 

        dclspc void Transition( spat::Position<Length>& pos ) const;
 
        dclspc void Transition( spat::Vector<One>& tan ) const;
 
        dclspc void Transition( spat::VectorBundle<Length,One>& bundle ) const;
 
        dclspc void Transition( spat::VectorBundle2<Length,One>& bundle ) const;
 
        dclspc void Transition( spat::Frame<Length,One>& frame ) const;
 
        dclspc void Transition( TrackData<Real>& td, Real engine_meters_per_unit ) const;
    

        dclspc std::pair<Length,bool> Move( Length dParam );
 
        dclspc std::pair<Length,bool> Move( Length dParam, const Event* pEvent );
 
        dclspc std::pair<Length,bool> Move( Length dParam, Orientation principalDirection, SignalTarget* pSignalTarget );
 
        dclspc std::pair<Length,bool> Move( Length dParam, Orientation principalDirection, const Event* pEvent, SignalTarget* pSignalTarget );
 

        dclspc Length MoveToEnd( Orientation direction = Orientation::Value::para, const Event* pEvent = nullptr, SignalTarget* pSignalTarget = nullptr );
 

        dclspc std::pair<Length,bool> MoveTransit( Orientation direction = Orientation::Value::para, const Event* pEvent = nullptr, SignalTarget* pSignalTarget = nullptr );
 

        dclspc Location& Flip() noexcept;
 

        dclspc bool Equals( const Location& loc, Length epsilon ) const noexcept;
 

        dclspc Length Distance( const Location& loc, Length maxdistance ) const;
 

        dclspc void Reserve( common::Interval<Length> range, IDType forID );
 

        dclspc void DeleteReservation( IDType forID = anyID );
 

        dclspc std::vector<Track::Overlap> Overlaps( IDType forID ) const;
 

        dclspc std::shared_ptr<Track> GetMutableTrack() const noexcept;
    private:
        std::shared_ptr<const Track>    m_pTrack;
        TrackLocation                   m_TLocation;
 
        // Calculates this track location relative to the coupled track at front or end.
        // This might lead to a parameter out of track ranges.
        // Returns false if the track is uncoupled at the specified end.
        bool TrackTransition( Track::EndType frontend, const Event* pEvent ) noexcept;
 
        // Transition tracks until parameter is on track.
        bool Resolve() noexcept;
 
        bool IsResolved() const noexcept;
    };
 
 
 
    inline bool operator==( const Location& locationA, const Location& locationB ) noexcept{
        return locationA.Equals( locationB, epsilon__length );
    }
 
    inline bool operator!=( const Location& locationA, const Location& locationB ) noexcept{
        return !locationA.Equals( locationB, epsilon__length );
    }
 

    dclspc Length ParameterDistanceFrom3DDistance( const Location& location, Length distanceIn3D, Length maxParameter, Length _epsilon = epsilon__length );
 

    dclspc std::tuple<std::shared_ptr<const Track>,Track::EndType,Length> EndOfLine( const Location& location, Length maxDistance, bool bDeadConnectorOnly = false );
}