Class TimeSpanMap<T>

  • Type Parameters:
    T - Type of the data.

    public class TimeSpanMap<T>
    extends Object
    Container for objects that apply to spans of time.

    Time span maps can be seen either as an ordered collection of time spans or as an ordered collection of transitions. Both views are dual one to each other. A time span extends from one transition to the next one, and a transition separates one time span from the next one. Each time span contains one entry that is valid during the time span; this entry may be null if nothing is valid during this time span.

    Typical uses of TimeSpanMap are to hold piecewise data, like for example an orbit count that changes at ascending nodes (in which case the entry would be an Integer), or a visibility status between several objects (in which case the entry would be a Boolean) or a drag coefficient that is expected to be estimated daily or three-hourly (this is how TimeSpanDragForce is implemented).

    Time span maps are built progressively. At first, they contain one time span only whose validity extends from past infinity to future infinity. Then new entries are added one at a time, associated with transition dates, in order to build up the complete map. The transition dates can be either the start of validity (when calling addValidAfter(Object, AbsoluteDate, boolean)), or the end of the validity (when calling addValidBefore(Object, AbsoluteDate, boolean)). Entries are often added at one end only (and mainly in chronological order), but this is not required. It is possible for example to first set up a map that cover a large range (say one day), and then to insert intermediate dates using for example propagation and event detectors to carve out some parts. This is akin to the way Binary Space Partitioning Trees work.

    Since 11.1, this class is thread-safe

    Since:
    7.1
    Author:
    Luc Maisonobe
    • Constructor Detail

      • TimeSpanMap

        public TimeSpanMap​(T entry)
        Create a map containing a single object, initially valid throughout the timeline.

        The real validity of this first entry will be truncated as other entries are either added before it or added after it.

        Parameters:
        entry - entry (initially valid throughout the timeline)
    • Method Detail

      • getSpansNumber

        public int getSpansNumber()
        Get the number of spans.

        The number of spans is always at least 1. The number of transitions is always 1 less than the number of spans.

        Returns:
        number of spans
        Since:
        11.1
      • addValidBefore

        public TimeSpanMap.Span<T> addValidBefore​(T entry,
                                                  AbsoluteDate latestValidityDate,
                                                  boolean erasesEarlier)
        Add an entry valid before a limit date.

        As an entry is valid, it truncates or overrides the validity of the neighboring entries already present in the map.

        If the map already contains transitions that occur earlier than latestValidityDate, the erasesEarlier parameter controls what to do with them. Lets consider the time span [tₖ ; tₖ₊₁[ associated with entry eₖ that would have been valid at time latestValidityDate prior to the call to the method (i.e. tₖ < latestValidityDate < tₖ₊₁).

        • if erasesEarlier is true, then all earlier transitions up to and including tₖ are erased, and the entry will be valid from past infinity to latestValidityDate
        • if erasesEarlier is false, then all earlier transitions are preserved, and the entry will be valid from tₖ to latestValidityDate

        In both cases, the existing entry eₖ time span will be truncated and will be valid only from latestValidityDate to tₖ₊₁.

        Parameters:
        entry - entry to add
        latestValidityDate - date before which the entry is valid
        erasesEarlier - if true, the entry erases all existing transitions that are earlier than latestValidityDate
        Returns:
        span with added entry
        Since:
        11.1
      • addValidAfter

        public TimeSpanMap.Span<T> addValidAfter​(T entry,
                                                 AbsoluteDate earliestValidityDate,
                                                 boolean erasesLater)
        Add an entry valid after a limit date.

        As an entry is valid, it truncates or overrides the validity of the neighboring entries already present in the map.

        If the map already contains transitions that occur later than earliestValidityDate, the erasesLater parameter controls what to do with them. Lets consider the time span [tₖ ; tₖ₊₁[ associated with entry eₖ that would have been valid at time earliestValidityDate prior to the call to the method (i.e. tₖ < earliestValidityDate < tₖ₊₁).

        • if erasesLater is true, then all later transitions from and including tₖ₊₁ are erased, and the entry will be valid from earliestValidityDate to future infinity
        • if erasesLater is false, then all later transitions are preserved, and the entry will be valid from earliestValidityDate to tₖ₊₁

        In both cases, the existing entry eₖ time span will be truncated and will be valid only from tₖ to earliestValidityDate.

        Parameters:
        entry - entry to add
        earliestValidityDate - date after which the entry is valid
        erasesLater - if true, the entry erases all existing transitions that are later than earliestValidityDate
        Returns:
        span with added entry
        Since:
        11.1
      • addValidBetween

        public TimeSpanMap.Span<T> addValidBetween​(T entry,
                                                   AbsoluteDate earliestValidityDate,
                                                   AbsoluteDate latestValidityDate)
        Add an entry valid between two limit dates.

        As an entry is valid, it truncates or overrides the validity of the neighboring entries already present in the map.

        Parameters:
        entry - entry to add
        earliestValidityDate - date after which the entry is valid
        latestValidityDate - date before which the entry is valid
        Returns:
        span with added entry
        Since:
        11.1
      • get

        public T get​(AbsoluteDate date)
        Get the entry valid at a specified date.

        The expected complexity is O(1) for successive calls with neighboring dates, which is the more frequent use in propagation or orbit determination applications, and O(n) for random calls.

        Parameters:
        date - date at which the entry must be valid
        Returns:
        valid entry at specified date
        See Also:
        getSpan(AbsoluteDate)
      • getSpan

        public TimeSpanMap.Span<T> getSpan​(AbsoluteDate date)
        Get the time span containing a specified date.

        The expected complexity is O(1) for successive calls with neighboring dates, which is the more frequent use in propagation or orbit determination applications, and O(n) for random calls.

        Parameters:
        date - date belonging to the desired time span
        Returns:
        time span containing the specified date
        Since:
        9.3
      • getFirstTransition

        public TimeSpanMap.Transition<T> getFirstTransition()
        Get the first (earliest) transition.
        Returns:
        first (earliest) transition, or null if there are no transitions
        Since:
        11.1
      • getLastTransition

        public TimeSpanMap.Transition<T> getLastTransition()
        Get the last (latest) transition.
        Returns:
        last (latest) transition, or null if there are no transitions
        Since:
        11.1
      • getFirstSpan

        public TimeSpanMap.Span<T> getFirstSpan()
        Get the first (earliest) span.
        Returns:
        first (earliest) span
        Since:
        11.1
      • getLastSpan

        public TimeSpanMap.Span<T> getLastSpan()
        Get the last (latest) span.
        Returns:
        last (latest) span
        Since:
        11.1
      • extractRange

        public TimeSpanMap<T> extractRange​(AbsoluteDate start,
                                           AbsoluteDate end)
        Extract a range of the map.

        The object returned will be a new independent instance that will contain only the transitions that lie in the specified range.

        Consider for example a map containing objects O₀ valid before t₁, O₁ valid between t₁ and t₂, O₂ valid between t₂ and t₃, O₃ valid between t₃ and t₄, and O₄ valid after t₄. then calling this method with a start date between t₁ and t₂ and a end date between t₃ and t₄ will result in a new map containing objects O₁ valid before t₂, O₂ valid between t₂ and t₃, and O₃ valid after t₃. The validity of O₁ is therefore extended in the past, and the validity of O₃ is extended in the future.

        Parameters:
        start - earliest date at which a transition is included in the range (may be set to AbsoluteDate.PAST_INFINITY to keep all early transitions)
        end - latest date at which a transition is included in the r (may be set to AbsoluteDate.FUTURE_INFINITY to keep all late transitions)
        Returns:
        a new instance with all transitions restricted to the specified range
        Since:
        9.2
      • forEach

        public void forEach​(Consumer<T> action)
        Performs an action for each non-null element of map.

        The action is performed chronologically.

        Parameters:
        action - action to perform on the non-null elements
        Since:
        10.3