sos.dated.util
Interface DatedList

All Superinterfaces:

DatedCollection, DatedObject

All Known Implementing Classes:

AbstractDatedList, sos.dated.util.AbstractListByDate, ArrayListByDate, ArrayListByElement

public interface DatedList

extends DatedCollection

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,Date), Adapters.asDatedList(List,Date,Date)

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Method Summary

void	add(int index, java.lang.Object value, java.util.Date from, java.util.Date to) Inserts an element into the list for a specified date range (optional operation).
Dates	addAll(int index, DatedCollection datedCollection) Inserts an entire dated collection into this dated list at the specified index (optional operation).
boolean	equals(java.util.Date date, DatedObject obj, java.util.Date objDate) Indicates if this dated object at date is equal to obj at objDate.
java.lang.Object	get(int index, java.util.Date date) Retrieves the element at the specified position on the specified date.
int	hashCode(java.util.Date date) Returns a hash code value of this dated list at the specified date.
int	indexOf(java.lang.Object value, java.util.Date date) Returns the position of the first occurrence of the specified element in this list at the specified date.
int	lastIndexOf(java.lang.Object value, java.util.Date date) Returns the position of the last occurrence of the specified element in this list at the specified date.
ListIterator	listIterator(java.util.Date date) Returns a list iterator over the elements of this dated list at the specified date.
ListIterator	listIterator(int index, java.util.Date date) Returns a list iterator over the elements of this dated list at the specified date, starting at the specified index.
DatedValue	remove(int index, java.util.Date from, java.util.Date to) Removes from this list the element at the specified position for the specified date range (optional operation).
DatedValue	set(int index, java.lang.Object value, java.util.Date from, java.util.Date to) Replaces the element at the specified position with the specified element for the specified date range.
DatedList	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

public void add(int index,
                java.lang.Object value,
                java.util.Date from,
                java.util.Date to)

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

Parameters:

index - position to insert the element

value - element to insert

from - starting date at which the element should be inserted

to - ending date at which the element should be inserted

Throws:

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

java.lang.UnsupportedOperationException - if this collection does not support add

java.lang.IllegalArgumentException - if index < 0

addAll

public Dates addAll(int index,
                    DatedCollection 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.IndexOutOfBoundsException - if index < 0 || index > size( d ) where d is a date when elements exist in datedCollection

java.lang.NullPointerException - datedCollection is null

equals

public boolean equals(java.util.Date date,
                      DatedObject obj,
                      java.util.Date objDate)

Description copied from interface: DatedObject

Indicates if this dated object at date is equal to obj at objDate.

Specified by:

equals in interface DatedObject

Parameters:

date - date at which this object should be tested

obj - the other dated object to be compared to

objDate - the date of the other dated object

Returns:

true if this dated object at date equals another dated object at objDate

get

public java.lang.Object get(int index,
                            java.util.Date date)

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

Parameters:

index - position to retrieve an element

date - date at which this list is to be queried

Returns:

the element at the specified position on the specified date

Throws:

java.lang.NullPointerException - if date is null

java.lang.IllegalArgumentException - if index < 0

hashCode

public int hashCode(java.util.Date date)

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

Parameters:

date - 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 date is null

indexOf

public int indexOf(java.lang.Object value,
                   java.util.Date date)

Returns the position of the first occurrence of the specified element in this list at the specified date.

Parameters:

value - element whose presence is to be tested

date -

Returns:

the position of the first occurrence of the specified element in this list at the specified date.

Throws:

java.lang.NullPointerException - if date is null

lastIndexOf

public int lastIndexOf(java.lang.Object value,
                       java.util.Date date)

Returns the position of the last occurrence of the specified element in this list at the specified date.

Parameters:

value - element whose presence is to be tested

date -

Returns:

the position of the first occurrence of the specified element in this list at the specified date.

Throws:

java.lang.NullPointerException - if date is null

listIterator

public ListIterator listIterator(java.util.Date date)

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

Parameters:

date - 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 date is null

listIterator

public ListIterator listIterator(int index,
                                 java.util.Date date)

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

date - 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.NullPointerException - if date is null

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

remove

public DatedValue remove(int index,
                         java.util.Date from,
                         java.util.Date to)

Removes from this 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 at which the element should be removed

to - ending date at which the element should be removed

Returns:

the element at the specified index from this list for the specified date range.

Throws:

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

java.lang.UnsupportedOperationException - if this collection does not support remove

java.lang.IllegalArgumentException - if index < 0

set

public DatedValue set(int index,
                      java.lang.Object value,
                      java.util.Date from,
                      java.util.Date to)

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

Parameters:

index - position to place the element

value - element to place in this list

from - starting date at which the position should be set

to - ending date at which the position should be set

Throws:

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

java.lang.UnsupportedOperationException - if this collection does not support set

java.lang.IllegalArgumentException

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

subList

public DatedList 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.

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