org.orekit.utils

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 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 and Description
static class	TimeSpanMap.Span<S> Holder for one time span.
static class	TimeSpanMap.Transition<S> Class holding transition times.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	addValidAfter(T entry, AbsoluteDate earliestValidityDate) Deprecated. as of 11.1, replaced by addValidAfter(Object, AbsoluteDate, boolean)
TimeSpanMap.Span<T>	addValidAfter(T entry, AbsoluteDate earliestValidityDate, boolean erasesLater) Add an entry valid after a limit date.
void	addValidBefore(T entry, AbsoluteDate latestValidityDate) Deprecated. as of 11.1, replaced by addValidBefore(Object, AbsoluteDate, boolean)
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.
NavigableSet<TimeSpanMap.Transition<T>>	getTransitions() Deprecated. as of 11.1, replaced by getFirstSpan(), getLastSpan(), getFirstTransition(), getLastTransition(), and getSpansNumber()

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

@Deprecated
public void addValidBefore(T entry,
                                       AbsoluteDate latestValidityDate)

Deprecated. as of 11.1, replaced by addValidBefore(Object, AbsoluteDate, boolean)

Add an entry valid before a limit date.

Calling this method is equivalent to call addValidAfter(entry, latestValidityDate, false).

Parameters:

entry - entry to add

latestValidityDate - date before which the entry is valid

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

@Deprecated
public void addValidAfter(T entry,
                                      AbsoluteDate earliestValidityDate)

Deprecated. as of 11.1, replaced by addValidAfter(Object, AbsoluteDate, boolean)

Add an entry valid after a limit date.

Calling this method is equivalent to call addValidAfter(entry, earliestValidityDate, false).

Parameters:

entry - entry to add

earliestValidityDate - date after which the entry is valid

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 earlier than earliestValidityDate, 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 earliestValidityDate prior to the call to the method (i.e. tₖ < earliestValidityDate < 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 earliestValidityDate
• if erasesEarlier is false, then all earlier transitions are preserved, and the entry will be valid from tₖ to earliestValidityDate

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

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

getTransitions

@Deprecated
public NavigableSet<TimeSpanMap.Transition<T>> getTransitions()

Deprecated. as of 11.1, replaced by getFirstSpan(), getLastSpan(), getFirstTransition(), getLastTransition(), and getSpansNumber()

Get copy of the sorted transitions.

Returns:

copy of the sorted transitions

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