sos.dated.util
Class DatedCollections

java.lang.Object
  |
  +--sos.dated.util.DatedCollections

public class DatedCollections

extends java.lang.Object

Views and algorithms that act on dated collections. This class is the equivalent to java.util.Collections that works on dated collections.

Specifically, it provides synchronized equivalents of the collections with the methods

• synchronizedDatedList(DatedList)
• synchronizedDatedMap(DatedMap)
• synchronizedDatedSet(DatedSet)
• synchronizedDatedSortedSet(DatedSortedSet)
• synchronizedDatedSortedMap(DatedSortedMap)
• synchronizedDatedValue(DatedValue)

It also provides read-only equivalents of the collections with the methods

• unmodifiableDatedList(DatedList)
• unmodifiableDatedMap(DatedMap)
• unmodifiableDatedSet(DatedSet)
• unmodifiableDatedSortedSet(DatedSortedSet)
• unmodifiableDatedSortedMap(DatedSortedMap)
• unmodifiableDatedValue(DatedValue)

Since:

1.0

See Also:

DatedCollection, DatedSet, DatedList, DatedMap, Adapters

Nested Class Summary

static interface

DatedCollections.Action Action to perform on a dated object at a period when it does not change.

Field Summary

static Dates	ALL_DATES An immutable series of dates with the range [MIN_DATE,MAX_DATE).
static DatedList	EMPTY_DATED_LIST An empty and immutable dated list.
static DatedMap	EMPTY_DATED_MAP An empty and immutable dated map.
static DatedSet	EMPTY_DATED_SET An empty and immutable dated set.
static Dates	EMPTY_DATES An empty and immutable series of dates.
static DatedValue	NULL_DATED_VALUE An immutable dated value with only null values.

Method Summary

static void	applyAtDates(DatedObject datedObject, java.util.Date from, java.util.Date to, DatedCollections.Action action) Performs the specified destructive action on the specified dated object withing the specified date range.
static int	binarySearch(DatedList datedList, java.lang.Object key, java.util.Comparator comparator, java.util.Date date) Searches for the specified key in the specified ordered list at the specified date, using the specified comparator, and returning the index of the key or the index of where the key would be inserted times negative one minus one.
static int	binarySearch(DatedList datedList, java.lang.Object key, java.util.Date date) Searches for the specified key in the specified ordered list at the specified date, returning the index of the key or the index of where the key would be inserted times negative one minus one.
static void	copy(DatedList datedList, java.util.List src, java.util.Date from, java.util.Date to) Copies the elements of src into datedList for the specified date range.
static void	fill(DatedList datedList, java.lang.Object obj, java.util.Date from, java.util.Date to) Fills the specified dated list with the specified element for the specified date range.
static int	indexOfSubList(DatedList datedList, java.util.List target, java.util.Date date) Returns the index of the first occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.
static int	lastIndexOfSubList(DatedList datedList, java.util.List target, java.util.Date date) Returns the index of the last occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.
static java.lang.Object	max(DatedCollection datedCollection, java.util.Comparator comparator, java.util.Date date) Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator.
static java.lang.Object	max(DatedCollection datedCollection, java.util.Date date) Returns the maximum value (according to the natural ordering) in the specified dated collection at the specified date.
static java.lang.Object	min(DatedCollection datedCollection, java.util.Comparator comparator, java.util.Date date) Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator.
static java.lang.Object	min(DatedCollection datedCollection, java.util.Date date) Returns the minimum value (according to the natural ordering) in the specified dated collection at the specified date.
static DatedList	nCopies(int n, java.lang.Object o, java.util.Date from, java.util.Date to) Returns an unmodifiable dated list containing exactly n copies of the specified object during the specified date range.
static void	queryAtDates(DatedObject datedObject, java.util.Date from, java.util.Date to, DatedCollections.Action action) Performs the specified non-destructive action on the specified dated object withing the specified date range.
static Dates	replaceAll(DatedList datedList, java.lang.Object oldVal, java.lang.Object newVal, java.util.Date from, java.util.Date to) Replaces all occurrences of oldVal with newVal in the specified list throughout the specified date range.
static void	reverse(DatedList datedList, java.util.Date from, java.util.Date to) Reverses the elements of the specified dated list in the specified date range.
static void	rotate(DatedList datedList, int distance, java.util.Date from, java.util.Date to) Shifts the elements of the specified dated list in the specified date range the specified distance.
static void	shuffle(DatedList datedList, java.util.Date from, java.util.Date to) Randomly rearranges the elements of the specified dated list in the specified date range The routine uses an internal random number generator.
static void	shuffle(DatedList datedList, java.util.Random rnd, java.util.Date from, java.util.Date to) Randomly rearranges the elements of the specified dated list in the specified date range, using the specified random number generator.
static DatedList	singletonDatedList(java.lang.Object o, java.util.Date from, java.util.Date to) Returns an unmodifiable dated list containing only the specified object during the specified date range.
static DatedMap	singletonDatedMap(java.lang.Object key, java.lang.Object value, java.util.Date from, java.util.Date to) Returns an unmodifiable dated map containing only the mapping of key to value during the specified date range.
static DatedSet	singletonDatedSet(java.lang.Object o, java.util.Date from, java.util.Date to) Returns an unmodifiable dated set containing only the specified object during the specified date range.
static void	sort(DatedList datedList, java.util.Comparator comparator, java.util.Date from, java.util.Date to) Sorts the elements of the specified dated list in the specified date range in ascending order, using the specified comparator.
static void	sort(DatedList datedList, java.util.Date from, java.util.Date to) Sorts the elements of the specified dated list in the specified date range in ascending order.
static void	swap(DatedList datedList, int i, int j, java.util.Date from, java.util.Date to) Exchanges the elements at indices i and j in the specified list at the specified date.
static DatedCollection	synchronizedDatedCollection(DatedCollection datedCollection) Returns a synchronized, or thread-safe, view of a dated collection.
static DatedList	synchronizedDatedList(DatedList datedList) Returns a synchronized, or thread-safe, view of a dated list.
static DatedMap	synchronizedDatedMap(DatedMap datedMap) Returns a synchronized, or thread-safe, view of a dated map.
static DatedObject	synchronizedDatedObject(DatedObject datedObject) Returns a synchronized, or thread-safe, view of a dated object.
static DatedSet	synchronizedDatedSet(DatedSet datedSet) Returns a synchronized, or thread-safe, view of a dated set.
static DatedSortedMap	synchronizedDatedSortedMap(DatedSortedMap datedSortedMap) Returns a synchronized, or thread-safe, view of a dated sorted map.
static DatedSortedSet	synchronizedDatedSortedSet(DatedSortedSet datedSortedSet) Returns a synchronized, or thread-safe, view of a dated sorted set.
static DatedValue	synchronizedDatedValue(DatedValue datedValue) Returns a synchronized, or thread-safe, view of a dated value.
static Dates	synchronizedDates(Dates dates) Returns a synchronized, or thread-safe, view of a series of date ranges.
static DatedCollection	unmodifiableDatedCollection(DatedCollection datedCollection) Returns an unmodifiable view of a dated collection.
static DatedList	unmodifiableDatedList(DatedList datedList) Returns an unmodifiable view of a dated list.
static DatedMap	unmodifiableDatedMap(DatedMap datedMap) Returns an unmodifiable view of a dated map.
static DatedSet	unmodifiableDatedSet(DatedSet datedSet) Returns an unmodifiable view of a dated set.
static DatedSortedMap	unmodifiableDatedSortedMap(DatedSortedMap datedSortedMap) Returns an unmodifiable view of a dated sorted map.
static DatedSortedSet	unmodifiableDatedSortedSet(DatedSortedSet datedSortedSet) Returns an unmodifiable view of a dated sorted set.
static DatedValue	unmodifiableDatedValue(DatedValue datedValue) Returns an unmodifiable view of a dated value.
static Dates	unmodifiableDates(Dates dates) Returns an unmodifiable view of a series of dates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALL_DATES

public static final Dates ALL_DATES

An immutable series of dates with the range [MIN_DATE,MAX_DATE). This Dates object is serializable and resolves to this same object when deserialized.

EMPTY_DATES

public static final Dates EMPTY_DATES

An empty and immutable series of dates. This Dates object is serializable and resolves to this same object when deserialized.

EMPTY_DATED_LIST

public static final DatedList EMPTY_DATED_LIST

An empty and immutable dated list. This dated list is serializable and resolves to this same object when deserialized.

EMPTY_DATED_SET

public static final DatedSet EMPTY_DATED_SET

An empty and immutable dated set. This dated set is serializable and resolves to this same object when deserialized.

EMPTY_DATED_MAP

public static final DatedMap EMPTY_DATED_MAP

An empty and immutable dated map. This dated map is serializable and resolves to this same object when deserialized.

NULL_DATED_VALUE

public static final DatedValue NULL_DATED_VALUE

An immutable dated value with only null values. This dated value is serializable and resolves to this same object when deserialized.

Method Detail

applyAtDates

public static void applyAtDates(DatedObject datedObject,
                                java.util.Date from,
                                java.util.Date to,
                                DatedCollections.Action action)

Performs the specified destructive action on the specified dated object withing the specified date range. The method first determines all dates of changes between from and to in datedObject. Then it invokes the action's perform method for the discovered ranges. A change to the dated object during perform does not alter the iteration over dates in away.

Parameters:

datedObject - target of action

from - start date of range (inclusive) to perform action

to - end date of range (exclusive) to perform action

action - destructive action to perform on datedObject between from and to

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

See Also:

queryAtDates(sos.dated.util.DatedObject, java.util.Date, java.util.Date, sos.dated.util.DatedCollections.Action)

queryAtDates

public static void queryAtDates(DatedObject datedObject,
                                java.util.Date from,
                                java.util.Date to,
                                DatedCollections.Action action)

Performs the specified non-destructive action on the specified dated object withing the specified date range. The action must not modify the dated object in such a way that an iteration over the dates of changes fails.

Parameters:

datedObject - target of action

from - start date of range (inclusive) to perform action

to - end date of range (exclusive) to perform action

action - non-destructive action to perform on datedObject between from and to

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

See Also:

applyAtDates(sos.dated.util.DatedObject, java.util.Date, java.util.Date, sos.dated.util.DatedCollections.Action)

unmodifiableDates

public static Dates unmodifiableDates(Dates dates)

Returns an unmodifiable view of a series of dates. Any attempt to modify the returned dates results in a run-time exception.

In this implementation, the returned Dates object "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned Dates object is serializable only if the parameter is serializable.

Parameters:

dates - dates to treat as read-only

Returns:

an unmodifiable view of dates

Throws:

java.lang.NullPointerException - if dates is null

unmodifiableDatedValue

public static DatedValue unmodifiableDatedValue(DatedValue datedValue)

Returns an unmodifiable view of a dated value. Any attempt to modify the returned value results in a run-time exception.

In this implementation, the returned value "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated value is serializable only if the parameter is serializable.

Parameters:

datedValue - dated value to treat as read-only

Returns:

an unmodifiable view of datedValue

Throws:

java.lang.NullPointerException - if the specified dated value is null

unmodifiableDatedCollection

public static DatedCollection unmodifiableDatedCollection(DatedCollection datedCollection)

Returns an unmodifiable view of a dated collection. Any attempt to modify the returned collection results in a run-time exception.

In this implementation, the returned collection "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated collection is serializable only if the parameter is serializable.

Parameters:

datedCollection - dated collection to treat as read-only

Returns:

an unmodifiable view of datedCollection

Throws:

java.lang.NullPointerException - if the specified dated collection is null

unmodifiableDatedSet

public static DatedSet unmodifiableDatedSet(DatedSet datedSet)

Returns an unmodifiable view of a dated set. Any attempt to modify the returned set results in a run-time exception.

In this implementation, the returned set "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated set is serializable only if the parameter is serializable.

Parameters:

datedSet - dated set to treat as read-only

Returns:

an unmodifiable view of datedSet

Throws:

java.lang.NullPointerException - if the specified dated set is null

unmodifiableDatedList

public static DatedList unmodifiableDatedList(DatedList datedList)

Returns an unmodifiable view of a dated list. Any attempt to modify the returned list results in a run-time exception.

In this implementation, the returned list "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated list is serializable only if the parameter is serializable. Also, the returned dated list implements RandomAccess if the parameter implements RandomAccess.

Parameters:

datedList - dated list to treat as read-only

Returns:

an unmodifiable view of datedList

Throws:

java.lang.NullPointerException - if the specified dated list is null

unmodifiableDatedMap

public static DatedMap unmodifiableDatedMap(DatedMap datedMap)

Returns an unmodifiable view of a dated map. Any attempt to modify the returned map results in a run-time exception.

In this implementation, the returned map "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated map is serializable only if the parameter is serializable.

Parameters:

datedMap - dated map to treat as read-only

Returns:

an unmodifiable view of datedMap

Throws:

java.lang.NullPointerException - if the specified dated map is null

unmodifiableDatedSortedMap

public static DatedSortedMap unmodifiableDatedSortedMap(DatedSortedMap datedSortedMap)

Returns an unmodifiable view of a dated sorted map. Any attempt to modify the returned sorted map results in a run-time exception.

In this implementation, the returned sorted map "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated sorted map is serializable only if the parameter is serializable.

Parameters:

datedSortedMap - dated sorted map to treat as read-only

Returns:

an unmodifiable view of datedSortedMap

Throws:

java.lang.NullPointerException - if the specified dated sorted map is null

unmodifiableDatedSortedSet

public static DatedSortedSet unmodifiableDatedSortedSet(DatedSortedSet datedSortedSet)

Returns an unmodifiable view of a dated sorted set. Any attempt to modify the returned sorted set results in a run-time exception.

In this implementation, the returned sorted set "wraps" the specified parameter in that it uses the parameter as its backing store. All query operations get passed to the backing store, and all update operations throw an UnsupportedOperationException.

The returned dated sorted set is serializable only if the parameter is serializable.

Parameters:

datedSortedSet - dated sorted set to treat as read-only

Returns:

an unmodifiable view of datedSortedSet

Throws:

java.lang.NullPointerException - if the specified dated sorted set is null

synchronizedDates

public static Dates synchronizedDates(Dates dates)

Returns a synchronized, or thread-safe, view of a series of date ranges. The returned Dates object synchronizes on itself at each method invocation and then passes the operation on to the parameter. Note that this implementation is coarse grained in that it does not allow concurrent access to disjoint date ranges of the object.

The client must manually synchronize on the returned Dates object in order to iterate over the ranges safely, as follows:

   Dates dates = ...
   Dateds syncDates = DatedCollections.synchronizedDates( dates );
   synchronized( syncDates ) {
     DateIterator dateIter = syncDates.dateIterator();
     while( dateIter.hasNext() ) {
       ...
     }
   }
 

The returned dated object is serializable only if the parameter is serializable.

Parameters:

dates - series of date ranges to be thread-safe

Returns:

a view of dates that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated object is null

synchronizedDatedObject

public static DatedObject synchronizedDatedObject(DatedObject datedObject)

Returns a synchronized, or thread-safe, view of a dated object. The returned dated object synchronizes on itself at each method invocation and then passes the operation on to the parameter. Note that this implementation is coarse grained in that it does not allow concurrent access to disjoint date ranges of the object.

The client must manually synchronize on the returned dated object in order to iterate over the dates safely, as follows:

   DateObject obj = ...
   DatedObject syncObj = DatedCollections.synchronizedDatedObject( obj );
   synchronized( syncObj ) {
     DateIterator dateIter = syncObj.dateIterator();
     while( dateIter.hasNext() ) {
       ...
     }
   }
 

To satisfy the contracts of equals(Date,DatedObject,Date) and hashCode(int) in subtypes that strengthen these contracts, the returned dated object does not forward these calls to the parameter.

The returned dated object is serializable only if the parameter is serializable.

Parameters:

datedObject - dated object to be thread-safe

Returns:

a view of datedObject that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated ibject is null

synchronizedDatedValue

public static DatedValue synchronizedDatedValue(DatedValue datedValue)

Returns a synchronized, or thread-safe, view of a dated value. The returned dated value synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated value is serializable only if the parameter is serializable.

Parameters:

datedValue - dated value to be thread-safe

Returns:

a view of datedValue that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated value is null

See Also:

synchronizedDatedObject(DatedObject)

synchronizedDatedCollection

public static DatedCollection synchronizedDatedCollection(DatedCollection datedCollection)

Returns a synchronized, or thread-safe, view of a dated collection. The returned dated collection synchronizes on itself at each method invocation and then passes the operation on to the parameter. The client must manually synchronize on the returned dated collection in order to iterate over the elements safely, as follows:

   Date someDate = ...
   DatedCollection coll = ...
   DatedCollection syncColl = DatedCollections.synchronizedDatedCollection( coll );
   synchronized( syncColl ) {
     Iterator iter = syncColl.iterator( someDate );
     while( iter.hasNext() ) {
       Object element = iter.next();
       ...
     }
   }
 

The returned dated collection is serializable only if the parameter is serializable.

Parameters:

datedCollection - dated collection to be thread-safe

Returns:

a view of datedCollection that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated collection is null

See Also:

synchronizedDatedObject(DatedObject)

synchronizedDatedSet

public static DatedSet synchronizedDatedSet(DatedSet datedSet)

Returns a synchronized, or thread-safe, view of a dated set. The returned dated set synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated set is serializable only if the parameter is serializable.

Parameters:

datedSet - dated set to be thread-safe

Returns:

a view of datedSet that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated set is null

See Also:

synchronizedDatedCollection(DatedCollection)

synchronizedDatedList

public static DatedList synchronizedDatedList(DatedList datedList)

Returns a synchronized, or thread-safe, view of a dated list. The returned dated list synchronizes on itself at each method invocation and then passes the operation on to the parameter.

The returned dated set is serializable only if the parameter is serializable. Also, the returned dated list implements RandomAccess if the parameter implements RandomAccess.

Parameters:

datedList - dated list to be thread-safe

Returns:

a view of datedList that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated list is null

See Also:

synchronizedDatedCollection(DatedCollection)

synchronizedDatedMap

public static DatedMap synchronizedDatedMap(DatedMap datedMap)

Returns a synchronized, or thread-safe, view of a dated map. The returned dated map synchronizes on itself at each method invocation and then passes the operation on to the parameter. The client must manually synchronize on the returned dated map in order to iterate over the mappings safely, as follows:

   Date someDate = ...
   DatedMap map = ...
   DatedMap syncMap = DatedCollections.synchronizedDatedMap( map );
   DatedSet entrySet = syncMap.entrySet();
   synchronized( syncMap ) {
     Iterator iter = entrySet.iterator( someDate );
     while( iter.hasNext() ) {
       DatedMap.Entry entry = (DatedMap.Entry)iter.next();
       ...
     }
   }
 

The returned dated map is serializable only if the parameter is serializable.

Parameters:

datedMap - dated map to be thread-safe

Returns:

a view of datedMap that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated map is null

See Also:

synchronizedDatedObject(DatedObject)

synchronizedDatedSortedMap

public static DatedSortedMap synchronizedDatedSortedMap(DatedSortedMap datedSortedMap)

Returns a synchronized, or thread-safe, view of a dated sorted map. The returned dated sorted map synchronizes on itself at each method invocation and then passes the operation on to the parameter. The map portions returned by headMap, subMap, and tailMap synchronize on the parent dated sorted map. Thus, before iterating over the mappings of these map portions, the client must manually synchronize on the full dated sorted map, as follows:

   Date someDate = ...
   DatedMap map = ...
   DatedMap syncMap = DatedCollections.synchronizedDatedMap( map );
   DatedMap headMap = syncMap.headMap( someKey );
   DatedSet entrySet = headMap.entrySet();
   synchronized( syncMap ) {
     Iterator iter = entrySet.iterator( someDate );
     while( iter.hasNext() ) {
       DatedMap.Entry entry = (DatedMap.Entry)iter.next();
       ...
     }
   }
 

The returned dated sorted map is serializable only if the parameter is serializable.

Parameters:

datedSortedMap - dated sorted map to be thread-safe

Returns:

a view of datedSortedMap that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated sorted map is null

See Also:

synchronizedDatedMap(DatedMap)

synchronizedDatedSortedSet

public static DatedSortedSet synchronizedDatedSortedSet(DatedSortedSet datedSortedSet)

Returns a synchronized, or thread-safe, view of a dated sorted set. The returned dated sorted set synchronizes on itself at each method invocation and then passes the operation on to the parameter. The map portions returned by headSet, subSet, and tailSet synchronize on the parent dated sorted set. Thus, before iterating over the mappings of these set portions, the client must manually synchronize on the full dated sorted set, as follows:

   Date someDate = ...
   DatedSet set = ...
   DatedSet syncSet = DatedCollections.synchronizedDatedSet( set );
   DatedMap tailSet = syncSet.tailSet( someElement );
   synchronized( syncSet ) {
     Iterator iter = tailSet.iterator( someDate );
     while( iter.hasNext() ) {
       Object element = iter.next();
       ...
     }
   }
 

The returned dated sorted set is serializable only if the parameter is serializable.

Parameters:

datedSortedSet - dated sorted set to be thread-safe

Returns:

a view of datedSortedSet that multiple threads may safely access

Throws:

java.lang.NullPointerException - if the specified dated sorted set is null

See Also:

synchronizedDatedCollection(DatedCollection)

sort

public static void sort(DatedList datedList,
                        java.util.Date from,
                        java.util.Date to)

Sorts the elements of the specified dated list in the specified date range in ascending order. The sorting algorithm uses the elements' natural ordering.

Parameters:

datedList - dated list to be sorted

from - start date of range (inclusive) to sort the list

to - end date of range (exclusive) to sort the list

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

sort

public static void sort(DatedList datedList,
                        java.util.Comparator comparator,
                        java.util.Date from,
                        java.util.Date to)

Sorts the elements of the specified dated list in the specified date range in ascending order, using the specified comparator. A null comparator causes the sorting algorithm to use the elements' natural ordering.

Parameters:

datedList - dated list to be sorted

comparator - comparator used to determine ascending order (may be null)

from - start date of range (inclusive) to sort the list

to - end date of range (exclusive) to sort the list

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

shuffle

public static void shuffle(DatedList datedList,
                           java.util.Date from,
                           java.util.Date to)

Randomly rearranges the elements of the specified dated list in the specified date range The routine uses an internal random number generator.

Parameters:

datedList - dated list to be shuffled

from - start date of range (inclusive) to shuffle the list

to - end date of range (exclusive) to shuffle the list

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

shuffle

public static void shuffle(DatedList datedList,
                           java.util.Random rnd,
                           java.util.Date from,
                           java.util.Date to)

Randomly rearranges the elements of the specified dated list in the specified date range, using the specified random number generator.

Parameters:

datedList - dated list to be sorted

rnd - random number generator used to determine the permutation

from - start date of range (inclusive) to sort the list

to - end date of range (exclusive) to sort the list

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

rotate

public static void rotate(DatedList datedList,
                          int distance,
                          java.util.Date from,
                          java.util.Date to)

Shifts the elements of the specified dated list in the specified date range the specified distance. A positive distance shifts the elements up in index, while a negative distance shifts the elements down in index. If (the absolute value of) distance is greater than the size of the list at any date within the range, then elements "circle back" to the beginning of the list. A distance of zero has no effect on the list.

Parameters:

datedList - dated list to be rotated

distance - number of indices to shift the elements of the list

from - start date of range (inclusive) to rotate the list

to - end date of range (exclusive) to rotate the list

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

reverse

public static void reverse(DatedList datedList,
                           java.util.Date from,
                           java.util.Date to)

Reverses the elements of the specified dated list in the specified date range.

Parameters:

datedList - dated list to be reversed

from - start date of range (inclusive) to reverse the list

to - end date of range (exclusive) to reverse the list

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

max

public static java.lang.Object max(DatedCollection datedCollection,
                                   java.util.Date date)

Returns the maximum value (according to the natural ordering) in the specified dated collection at the specified date.

Parameters:

datedCollection - dated collection to be searched

date - date to search the collection

Returns:

the maximum element in datedCollection at date, according to their natural ordering

Throws:

java.lang.NullPointerException - if any argument is null

See Also:

max(DatedCollection,Comparator,Date), min(DatedCollection,Date)

max

public static java.lang.Object max(DatedCollection datedCollection,
                                   java.util.Comparator comparator,
                                   java.util.Date date)

Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator. A null comparator indicates that the method should use the elements' natural ordering.

Parameters:

datedCollection - dated collection to be searched

comparator - comparator used to order the elements (may be null)

date - date to search the collection

Returns:

the maximum element in datedCollection at date, according to the comparator

Throws:

java.lang.NullPointerException - if datedCollection or date is null

See Also:

max(DatedCollection,Date), min(DatedCollection,Comparator,Date)

min

public static java.lang.Object min(DatedCollection datedCollection,
                                   java.util.Date date)

Returns the minimum value (according to the natural ordering) in the specified dated collection at the specified date.

Parameters:

datedCollection - dated collection to be searched

date - date to search the collection

Returns:

the minimum element in datedCollection at date, according to their natural ordering

Throws:

java.lang.NullPointerException - if any argument is null

See Also:

min(DatedCollection,Comparator,Date), max(DatedCollection,Date)

min

public static java.lang.Object min(DatedCollection datedCollection,
                                   java.util.Comparator comparator,
                                   java.util.Date date)

Returns the maximum value in the specified dated collection at the specified date, according to the specified comparator. A null comparator indicates that the method should use the elements' natural ordering.

Parameters:

datedCollection - dated collection to be searched

comparator - comparator used to order the elements (may be null)

date - date to search the collection

Returns:

the maximum element in datedCollection at date, according to the comparator

Throws:

java.lang.NullPointerException - if datedCollection or date is null

See Also:

min(DatedCollection,Date), max(DatedCollection,Comparator,Date)

binarySearch

public static int binarySearch(DatedList datedList,
                               java.lang.Object key,
                               java.util.Date date)

Searches for the specified key in the specified ordered list at the specified date, returning the index of the key or the index of where the key would be inserted times negative one minus one.

Parameters:

datedList - dated list to be searched

key - element to look for in the list

date - date to search the list

Returns:

either i, where i is the index of the key in datedList at date, or -i-1, where i is the index of the key if it were in the list

Throws:

java.lang.NullPointerException - if datedList or date is null

binarySearch

public static int binarySearch(DatedList datedList,
                               java.lang.Object key,
                               java.util.Comparator comparator,
                               java.util.Date date)

Searches for the specified key in the specified ordered list at the specified date, using the specified comparator, and returning the index of the key or the index of where the key would be inserted times negative one minus one. A null comparator causes the method to use the elements' natural ordering.

Parameters:

datedList - dated list to be searched

key - element to look for in the list

comparator - comparator used to order the elements of the list (may be null)

date - date to search the list

Returns:

either i, where i is the index of the key in datedList at date, or -i-1, where i is the index of the key if it were in the list

Throws:

java.lang.NullPointerException - if datedList or date is null

swap

public static void swap(DatedList datedList,
                        int i,
                        int j,
                        java.util.Date from,
                        java.util.Date to)

Exchanges the elements at indices i and j in the specified list at the specified date.

Parameters:

datedList - dated list holding the elements to be swapped

i - index of an element to be swapped

j - index of the other element to be swapped

from - start date of range (inclusive) to perform the swap

to - end date of range (exclusive) to perform the swap

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

java.lang.IndexOutOfBoundsException - if i > size(d) or j > size(d) for any d between from and to

replaceAll

public static Dates replaceAll(DatedList datedList,
                               java.lang.Object oldVal,
                               java.lang.Object newVal,
                               java.util.Date from,
                               java.util.Date to)

Replaces all occurrences of oldVal with newVal in the specified list throughout the specified date range.

Parameters:

datedList - dated list holding the elements to replace

oldVal - element to replace

newVal - element to substitute for oldVal

from - start date of range (inclusive) to perform the substitution

to - end date of range (exclusive) to perform the substitution

Returns:

list of date ranges indicating when a substitution occurred

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

fill

public static void fill(DatedList datedList,
                        java.lang.Object obj,
                        java.util.Date from,
                        java.util.Date to)

Fills the specified dated list with the specified element for the specified date range.

Parameters:

datedList - dated list to fill

obj - element to put in list

from - start date of range (inclusive) to fill the list

to - end date of range (exclusive) to fill the list

Throws:

java.lang.NullPointerException - if datedList, from, or to is null

java.lang.IllegalArgumentException - if from does not precede to

indexOfSubList

public static int indexOfSubList(DatedList datedList,
                                 java.util.List target,
                                 java.util.Date date)

Returns the index of the first occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.

Parameters:

datedList - dated list to search

target - list elements to search for

date - date to check for occurrence in the dated list

Returns:

the index of the first occurrence of target in datedList at date, or -1 if target never occurs

Throws:

java.lang.NullPointerException - if any argument is null

lastIndexOfSubList

public static int lastIndexOfSubList(DatedList datedList,
                                     java.util.List target,
                                     java.util.Date date)

Returns the index of the last occurrence of target in the specified dated list at the specified date, or -1 if it never occurs.

Parameters:

datedList - dated list to search

target - list elements to search for

date - date to check for occurrence in the dated list

Returns:

the index of the last occurrence of target in datedList at date, or -1 if target never occurs

Throws:

java.lang.NullPointerException - if any argument is null

copy

public static void copy(DatedList datedList,
                        java.util.List src,
                        java.util.Date from,
                        java.util.Date to)

Copies the elements of src into datedList for the specified date range.

Parameters:

datedList - dated list to copy into

src - list of elements to copy

from - start date of range (inclusive) to copy into

to - end date of range (exclusive) to copy into

Throws:

java.lang.NullPointerException - if any argument is null

java.lang.IllegalArgumentException - if from does not precede to

singletonDatedSet

public static DatedSet singletonDatedSet(java.lang.Object o,
                                         java.util.Date from,
                                         java.util.Date to)

Returns an unmodifiable dated set containing only the specified object during the specified date range.

Parameters:

o - object to include in the returned set

from - start date of range (inclusive) for the returned dated set to contain the object

to - end date of range (exclusive) for the returned dated set to contain the object

Returns:

an unmodifiable dated set containing only o between from and to

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

singletonDatedList

public static DatedList singletonDatedList(java.lang.Object o,
                                           java.util.Date from,
                                           java.util.Date to)

Returns an unmodifiable dated list containing only the specified object during the specified date range.

Parameters:

o - object to include in the returned list

from - start date of range (inclusive) for the returned dated list to contain the object

to - end date of range (exclusive) for the returned dated list to contain the object

Returns:

an unmodifiable dated list containing only o between from and to

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

singletonDatedMap

public static DatedMap singletonDatedMap(java.lang.Object key,
                                         java.lang.Object value,
                                         java.util.Date from,
                                         java.util.Date to)

Returns an unmodifiable dated map containing only the mapping of key to value during the specified date range.

Parameters:

key - key to include in the returned map

value - value to be associated with key in the returned map

from - start date of range (inclusive) for the returned dated map to contain the object

to - end date of range (exclusive) for the returned dated map to contain the object

Returns:

an unmodifiable dated map containing only o between from and to

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to

nCopies

public static DatedList nCopies(int n,
                                java.lang.Object o,
                                java.util.Date from,
                                java.util.Date to)

Returns an unmodifiable dated list containing exactly n copies of the specified object during the specified date range.

Parameters:

n - number of copies of o to include in the returned list

o - object to include in the returned list

from - start date of range (inclusive) for the returned dated list to contain n copies of the object

to - end date of range (exclusive) for the returned dated list to contain n copies of the object

Returns:

an unmodifiable dated list containing exactly n copies of o between from and to

Throws:

java.lang.NullPointerException - if from or to is null

java.lang.IllegalArgumentException - if from does not precede to or if n < 0