java.lang.Object
- org.orekit.utils.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

Nested Class Summary

Nested Classes
Modifier and Type Class Description

static class TimeSpanMap.Span<S>
Holder for one time span.

static class TimeSpanMap.Transition<S>
Class holding transition times.

Constructor Summary

Constructors
Constructor Description

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

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`TimeSpanMap.Span<T>`	`addValidAfter(T entry, AbsoluteDate earliestValidityDate, boolean erasesLater)`	Add an entry valid after a limit date.
`TimeSpanMap.Span<T>`	`addValidBefore(T entry, AbsoluteDate latestValidityDate, boolean erasesEarlier)`	Add an entry valid before a limit date.
`TimeSpanMap.Span<T>`	`addValidBetween(T entry, AbsoluteDate earliestValidityDate, AbsoluteDate latestValidityDate)`	Add an entry valid between two limit dates.
`TimeSpanMap<T>`	`extractRange(AbsoluteDate start, AbsoluteDate end)`	Extract a range of the map.
`void`	`forEach(Consumer<T> action)`	Performs an action for each non-null element of map.
`T`	`get(AbsoluteDate date)`	Get the entry valid at a specified date.
`TimeSpanMap.Span<T>`	`getFirstSpan()`	Get the first (earliest) span.
`TimeSpanMap.Transition<T>`	`getFirstTransition()`	Get the first (earliest) transition.
`TimeSpanMap.Span<T>`	`getLastSpan()`	Get the last (latest) span.
`TimeSpanMap.Transition<T>`	`getLastTransition()`	Get the last (latest) transition.
`TimeSpanMap.Span<T>`	`getSpan(AbsoluteDate date)`	Get the time span containing a specified date.
`int`	`getSpansNumber()`	Get the number of spans.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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

Modifier and Type	Class	Description
`static class`	`TimeSpanMap.Span<S>`	Holder for one time span.
`static class`	`TimeSpanMap.Transition<S>`	Class holding transition times.

Class TimeSpanMap<T>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TimeSpanMap

Method Detail

getSpansNumber

addValidBefore

addValidAfter

addValidBetween

get

getSpan

getFirstTransition

getLastTransition

getFirstSpan

getLastSpan

extractRange

forEach