Side of Software
Dated Collections Library 2.0

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.

ArrayListByDateArrayListByElement
addT*NT (amortized)
add(i)T*NT*N
clearTT*N
containslog(T)+Nlog(T)*N
containsThroughoutT*NT*N
dateIteratorlog(T)T*N
getlog(T)log(T)
hashCodeT*NT*N
hashCode(d)log(T)+Nlog(T)*N
indexOflog(T)+Nlog(T)*N
iteratorlog(T)log(T)
lastIndexOflog(T)+Nlog(T)*N
listIteratorlog(T)log(T)
removeT*NT*N
remove(i)T*NT*N
setT*NT
sizelog(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

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.