sos.dated.util
Interface DatedList<E,D>

Type Parameters:

E - the type of elements maintained by this dated list

D - the type of dates used by this dated list

All Superinterfaces:

DatedCollection<E,D>, DatedObject<D>

All Known Implementing Classes:

AbstractDatedList, AbstractSequentialDatedList, ArrayListByDate, ArrayListByElement

public interface DatedList<E,D>
extends DatedCollection<E,D>

A list of elements over time.

The following table compares the efficiencies of the two implementations in this package. Each cell is the average big-Oh notation, where T denotes the number of dates in the map and N denotes the number of elements at any given date.

	ArrayListByDate	ArrayListByElement
add	T*N	T (amortized)
add(i)	T*N	T*N
clear	T	T*N
contains	log(T)+N	log(T)*N
containsThroughout	T*N	T*N
dateIterator	log(T)	T*N
get	log(T)	log(T)
hashCode	T*N	T*N
hashCode(d)	log(T)+N	log(T)*N
indexOf	log(T)+N	log(T)*N
iterator	log(T)	log(T)
lastIndexOf	log(T)+N	log(T)*N
listIterator	log(T)	log(T)
remove	T*N	T*N
remove(i)	T*N	T*N
set	T*N	T
size	log(T)	log(T)

The interface is based on the interface java.util.List. This interface does not extend java.util.List directly because at least one date is needed. To make a dated list appear like a non-dated list, use Adapters.asList(DatedList,Date). Similarly, to treat a non-dated collection as dated, use Adapters.asDatedList(List,Date,Date).

Since:

1.0

See Also:

ArrayListByDate, ArrayListByElement, Adapters.asList(DatedList,Object), Adapters.asDatedList(List,Object,Object)

Method Summary

void	add(int index, E value, D from, D to) Inserts an element into this dated list for a specified date range (optional operation).
Dates<D>	addAll(int index, DatedCollection<? extends E,D> datedCollection) Inserts an entire dated collection into this dated list at the specified index (optional operation).
boolean	equals(D at, DatedObject<D> obj, D objAt) Indicates if this dated object at at is equal to obj at objAt.
E	get(int index, D at) Retrieves the element at the specified position on the specified date.
int	hashCode(D at) Returns a hash code value of this dated list at the specified date.
int	indexOf(java.lang.Object value, D at) Returns the position of the first occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.
int	lastIndexOf(java.lang.Object value, D at) Returns the position of the last occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.
ListIterator<E,D>	listIterator(D at) Returns a list iterator over the elements of this dated list at the specified date.
ListIterator<E,D>	listIterator(int index, D at) Returns a list iterator over the elements of this dated list at the specified date, starting at the specified index.
DatedValue<E,D>	remove(int index, D from, D to) Removes from this dated list the element at the specified position for the specified date range (optional operation).
DatedValue<E,D>	set(int index, E value, D from, D to) Replaces the element at the specified position with the specified element for the specified date range.
DatedList<E,D>	subList(int fromIndex, int toIndex) Returns a view of this dated list restricted to the range fromIndex, inclusive, to toIndex, exclusive.

Methods inherited from interface sos.dated.util.DatedCollection

add, addAll, clear, contains, containsAll, containsThroughout, excludesThroughout, hasSizeThroughout, isEmpty, isEmptyThroughout, iterator, remove, removeAll, retainAll, size, toArray, toArray

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, dateIterator, equals, hashCode, toString

Method Detail

add

void add(int index,
         E value,
         D from,
         D to)

Inserts an element into this dated list for a specified date range (optional operation).

Parameters:

index - position to insert the element

value - element to insert

from - starting date (inclusive) at which the element should be inserted

to - ending date (exclusive) at which the element should be inserted

Throws:

java.lang.ClassCastException - if the underlying type of value prevents it from being added to this dated list

java.lang.IllegalArgumentException - if from does not precede to or if some property of value prevents it from being added to this dated list

java.lang.IndexOutOfBoundsException - if index < 0 || index > size( d ) where d is a date between from and to

java.lang.NullPointerException - if from or to is null or if value is null and this dated list cannot hold null elements

java.lang.UnsupportedOperationException - if this dated list does not support add

addAll

Dates<D> addAll(int index,
                DatedCollection<? extends E,D> datedCollection)

Inserts an entire dated collection into this dated list at the specified index (optional operation).

Parameters:

index - index at which to insert the dated collection

datedCollection - collection to insert into this dated list

Returns:

a series of date ranges for which this list changed

Throws:

java.lang.ClassCastException - if the type of an element of datedCollection prevents it from being added to this dated list

java.lang.IllegalArgumentException - if some property of an element of datedCollection prevents it from being added to this dated list

java.lang.IndexOutOfBoundsException - if index < 0 || index > size( d ) where d is a date when elements exist in datedCollection

java.lang.NullPointerException - if datedCollection is null or if an element of datedCollection is null and this dated list cannot hold null elements

java.lang.UnsupportedOperationException - if this dated list does not support addAll

equals

boolean equals(D at,
               DatedObject<D> obj,
               D objAt)

Description copied from interface: DatedObject

Indicates if this dated object at at is equal to obj at objAt.

Specified by:

equals in interface DatedObject<D>

Parameters:

at - date at which this object should be tested

obj - the other dated object to be compared to

objAt - the date of the other dated object

Returns:

true if this dated object at at equals another dated object at objAt

get

E get(int index,
      D at)

Retrieves the element at the specified position on the specified date.

Parameters:

index - position to retrieve an element

at - date at which this dated list is to be queried

Returns:

the element at the specified position on the specified date

Throws:

java.lang.IndexOutOfBoundsException - if index < 0 || index >= size( at )

java.lang.NullPointerException - if at is null

hashCode

int hashCode(D at)

Returns a hash code value of this dated list at the specified date. The hash code of a DatedList at a date is calculated the same way as in hashCode of java.util.List.

Specified by:

hashCode in interface DatedObject<D>

Parameters:

at - date to which the value should correspond

Returns:

the hash code value of this dated object at the specified date

Throws:

java.lang.NullPointerException - if at is null

indexOf

int indexOf(java.lang.Object value,
            D at)

Returns the position of the first occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.

Parameters:

value - element whose presence is to be tested

at - date to search for the element

Returns:

the position of the first occurrence of the specified element in this dated list at the specified date, or -1 if not present.

Throws:

java.lang.NullPointerException - if at is null

lastIndexOf

int lastIndexOf(java.lang.Object value,
                D at)

Returns the position of the last occurrence of the specified element in this list at the specified date, or -1 if this dated list does not contain the element at that date.

Parameters:

value - element whose presence is to be tested

at - date to search for the element

Returns:

the position of the last occurrence of the specified element in this dated list at the specified date, or -1 if not present.

Throws:

java.lang.NullPointerException - if at is null

listIterator

ListIterator<E,D> listIterator(D at)

Returns a list iterator over the elements of this dated list at the specified date.

Parameters:

at - date at which to iterate over the elements of this dated list

Returns:

a list iterator at the specified date

Throws:

java.lang.NullPointerException - if at is null

listIterator

ListIterator<E,D> listIterator(int index,
                               D at)

Returns a list iterator over the elements of this dated list at the specified date, starting at the specified index.

Parameters:

index - position at which to start the iteration

at - date at which to iterate over the elements of this dated list

Returns:

a list iterator at the specified date with the specified index as its starting position

Throws:

java.lang.IndexOutOfBoundsException - if index < 0 || index >= size( at )

java.lang.NullPointerException - if at is null

remove

DatedValue<E,D> remove(int index,
                       D from,
                       D to)

Removes from this dated list the element at the specified position for the specified date range (optional operation).

Parameters:

index - position at which to start the iteration

from - starting date (inclusive) at which the element should be removed

to - ending date (exclusive) at which the element should be removed

Returns:

the elements previously at the specified index from this list for the specified date range.

Throws:

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

java.lang.IndexOutOfBoundsException - if index < 0 || index >= size( d ) where d is a date within the specified range

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

java.lang.UnsupportedOperationException - if this dated list does not support remove

set

DatedValue<E,D> set(int index,
                    E value,
                    D from,
                    D to)

Replaces the element at the specified position with the specified element for the specified date range.

Parameters:

index - position of the element to replace

value - element to place in this list

from - starting date (inclusive) at which the position should be set

to - ending date (exclusive) at which the position should be set

Throws:

java.lang.ClassCastException - if the underlying type of value prevents it from being added to this dated list

java.lang.IllegalArgumentException - if from does not precede to or if some property of value prevents it from being added to this dated list

java.lang.IndexOutOfBoundsException - if this dated list does not contain index + 1 elements throughout the specified date range

java.lang.NullPointerException - if from or to is null or if value is null and this dated list cannot hold null elements

java.lang.UnsupportedOperationException - if this dated list does not support set

subList

DatedList<E,D> subList(int fromIndex,
                       int toIndex)

Returns a view of this dated list restricted to the range fromIndex, inclusive, to toIndex, exclusive. Changes made to the returned sub-list are reflected in the master list, and vice versa.

For the date ranges where the interval [fromIndex,toIndex) is not present in this dated list, some sub-list operations will throw an IllegalArgumentException. For example, consider the following code, where d0, d1, etc. are consecutive dates:

  DatedList list = new ArrayListByDate();
  list.add( "A", d0, d2 );
  list.add( "B", d1, d2 );
  DatedList subList = list.subList( 1, 2 );

  subList.add( "C", d1, d2 ); // successful
  subList.add( "C", d0, d2 ); // fails because list does not have
                              // 2 elements at d0

  int size = subList.size( d0 );  // returns 0
  size = subList.size( d1 );      // returns 1

  subList.get( 0, d0 );           // fails
 

Therefore, it is only safe to use the sub-list during date ranges where the interval [fromIndex,toIndex) exists in this list.

Parameters:

fromIndex - starting position of the returned view (inclusive)

toIndex - ending position of the returned view (exclusive)

Returns:

a fully modifiable view of this dated list restricted to the specified range