Class TimeSpanMap<T>
- 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 oftransitions
. 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 anInteger
), or a visibility status between several objects (in which case the entry would be aBoolean
) or a drag coefficient that is expected to be estimated daily or three-hourly.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 callingaddValidAfter(Object, AbsoluteDate, boolean)
), or the end of the validity (when callingaddValidBefore(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>
getFirstNonNullSpan()
Get the first (earliest) span with non-null data.TimeSpanMap.Span<T>
getFirstSpan()
Get the first (earliest) span.TimeSpanMap.Transition<T>
getFirstTransition()
Get the first (earliest) transition.TimeSpanMap.Span<T>
getLastNonNullSpan()
Get the last (latest) span with non-null data.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.
-
-
-
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 oradded 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
, theerasesEarlier
parameter controls what to do with them. Lets consider the time span [tₖ ; tₖ₊₁[ associated with entry eₖ that would have been valid at timelatestValidityDate
prior to the call to the method (i.e. tₖ <latestValidityDate
< tₖ₊₁).- if
erasesEarlier
istrue
, then all earlier transitions up to and including tₖ are erased, and theentry
will be valid from past infinity tolatestValidityDate
- if
erasesEarlier
isfalse
, then all earlier transitions are preserved, and theentry
will be valid from tₖ tolatestValidityDate
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 addlatestValidityDate
- date before which the entry is validerasesEarlier
- if true, the entry erases all existing transitions that are earlier thanlatestValidityDate
- Returns:
- span with added entry
- Since:
- 11.1
- if
-
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
, theerasesLater
parameter controls what to do with them. Lets consider the time span [tₖ ; tₖ₊₁[ associated with entry eₖ that would have been valid at timeearliestValidityDate
prior to the call to the method (i.e. tₖ <earliestValidityDate
< tₖ₊₁).- if
erasesLater
istrue
, then all later transitions from and including tₖ₊₁ are erased, and theentry
will be valid fromearliestValidityDate
to future infinity - if
erasesLater
isfalse
, then all later transitions are preserved, and theentry
will be valid fromearliestValidityDate
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 addearliestValidityDate
- date after which the entry is validerasesLater
- if true, the entry erases all existing transitions that are later thanearliestValidityDate
- Returns:
- span with added entry
- Since:
- 11.1
- if
-
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 addearliestValidityDate
- date after which the entry is validlatestValidityDate
- 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
-
getFirstNonNullSpan
public TimeSpanMap.Span<T> getFirstNonNullSpan()
Get the first (earliest) span with non-null data.- Returns:
- first (earliest) span with non-null data
- Since:
- 12.1
-
getLastSpan
public TimeSpanMap.Span<T> getLastSpan()
Get the last (latest) span.- Returns:
- last (latest) span
- Since:
- 11.1
-
getLastNonNullSpan
public TimeSpanMap.Span<T> getLastNonNullSpan()
Get the last (latest) span with non-null data.- Returns:
- last (latest) span with non-null data
- Since:
- 12.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 aend
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 toAbsoluteDate.PAST_INFINITY
to keep all early transitions)end
- latest date at which a transition is included in the r (may be set toAbsoluteDate.FUTURE_INFINITY
to keep all late transitions)- Returns:
- a new instance with all transitions restricted to the specified range
- Since:
- 9.2
-
-