sos.dated.util
Class HashSetByElement<E,D>

java.lang.Object
  sos.dated.util.AbstractDatedObject<D>
      sos.dated.util.AbstractDatedCollection<E,D>
          sos.dated.util.AbstractDatedSet<E,D>
              sos.dated.util.HashSetByElement<E,D>

Type Parameters:

E - the type of elements maintained by this dated set

D - the type of dates used by this dated set

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, DatedCollection<E,D>, DatedObject<D>, DatedSet<E,D>

public class HashSetByElement<E,D>
extends AbstractDatedSet<E,D>
implements DatedSet<E,D>, java.io.Serializable, java.lang.Cloneable

An implementation of DatedSet that uses a HashMapByKey as its underlying data structure. The following illustration shows a conceptual view of a small HashSetByElement where the "dates" are integers and the elements are characters:

In the above picture, the dated set contains the following elements for the following ranges:

   [1,2): {K,B,M}
   [3,5): {K,A,B,M}
   [5,6): {M}
   [6,9): {K,A,B}

This implementation is serializable and cloneable; however, it is not synchronized. To use it safely in a multi-threaded situation, wrap an instance of the dated set with a call to DatedCollections.synchronizedDatedSet.

Since:

1.0

See Also:

HashSetByDate, TreeSetByElement, DatedSet, HashMapByKey, DatedCollections.synchronizedDatedSet(DatedSet)

Constructor Summary

HashSetByElement()
Creates a new instance of HashSetByElement.

HashSetByElement(DatedCollection<? extends E,D> datedCollection)
Creates a new instance of HashSetByElement initialized with the elements and dates of the specified dated collection.

HashSetByElement(int initialCapacity)
Creates a new instance of HashSetByElement with the specified initial capacity and default load factor (0.75).

HashSetByElement(int initialCapacity, float loadFactor)
Creates a new instance of HashSetByElement with the specified initial capacity and load factor.

Method Summary

Dates<D>	add(E value, D from, D to) Adds the specified element to this dated collection for the specified date range.
void	clear(D from, D to) Removes all elements from this dated collection for the specified dates.
java.lang.Object	clone() Creates and returns a shallow copy of this object.
boolean	contains(java.lang.Object value, D date) Returns true if this dated collection contains the specified element on the specified date.
boolean	containsThroughout(java.lang.Object value, D from, D to) Returns true if this dated collection contains the specified element throughout the specified date range.
DateIterator<D>	dateIterator(D at) Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date.
boolean	excludesThroughout(java.lang.Object value, D from, D to) Returns true if this dated collection does not contain the specified element at any date within the specified date range.
boolean	hasSizeThroughout(int size, D from, D to) Returns true if the number of elements in this dated collection is greater than or equal to the specified size throughout the specified date range.
boolean	isEmpty(D at) Returns true if this dated collection contains no elements on the specified date.
boolean	isEmptyThroughout(D from, D to) Returns true if this dated collection contains no elements throughout the specified date range.
Iterator<E,D>	iterator(D at) Returns an iterator over the elements of this dated collection at the specified date.
Dates<D>	remove(java.lang.Object value, D from, D to) Removes an instance of the specified element from this dated collection for the specified date range.
int	size(D at) Returns the number of elements in this dated collection at the specified date.

Methods inherited from class sos.dated.util.AbstractDatedSet

equals, hashCode

Methods inherited from class sos.dated.util.AbstractDatedCollection

addAll, containsAll, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class sos.dated.util.AbstractDatedObject

dateIterator, equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface sos.dated.util.DatedSet

equals, hashCode

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

Constructor Detail

HashSetByElement

public HashSetByElement()

Creates a new instance of HashSetByElement.

HashSetByElement

public HashSetByElement(int initialCapacity)

Creates a new instance of HashSetByElement with the specified initial capacity and default load factor (0.75). The initial capacity is used to initialize the underlying HashMapByKey, which holds all elements across all time.

Parameters:

initialCapacity - initial capacity of the underlying hash map

Throws:

java.lang.IllegalArgumentException - if initialCapacity < 0

HashSetByElement

public HashSetByElement(int initialCapacity,
                        float loadFactor)

Creates a new instance of HashSetByElement with the specified initial capacity and load factor.

Parameters:

initialCapacity - load capacity of the underlying hash map

loadFactor - load factor of the underlying hash map

Throws:

java.lang.IllegalArgumentException - if initialCapacity < 0 or if loadFactor <= 0.0

HashSetByElement

public HashSetByElement(DatedCollection<? extends E,D> datedCollection)

Creates a new instance of HashSetByElement initialized with the elements and dates of the specified dated collection.

Parameters:

datedCollection - collection with which to initialize the new HashSetByElement

Method Detail

clone

public java.lang.Object clone()

Creates and returns a shallow copy of this object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this instance

add

public Dates<D> add(E value,
                    D from,
                    D to)

Adds the specified element to this dated collection for the specified date range.

Specified by:

add in interface DatedCollection<E,D>

Overrides:

add in class AbstractDatedCollection<E,D>

Parameters:

value - element to add

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

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

Returns:

a series of date ranges indicating when the addition changed this dated collection

Throws:

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

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

clear

public void clear(D from,
                  D to)

Removes all elements from this dated collection for the specified dates.

Specified by:

clear in interface DatedCollection<E,D>

Overrides:

clear in class AbstractDatedCollection<E,D>

Parameters:

from - starting date (inclusive) at which this dated collection should be cleared

to - ending date (exclusive) at which this dated collection should be cleared

Throws:

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

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

contains

public boolean contains(java.lang.Object value,
                        D date)

Returns true if this dated collection contains the specified element on the specified date.

Specified by:

contains in interface DatedCollection<E,D>

Overrides:

contains in class AbstractDatedCollection<E,D>

Parameters:

value - element whose presence is to be tested

date - date at which this collection is to be queried

Returns:

true if this dated collection contains the specified element on the specified date

Throws:

java.lang.NullPointerException - if at is null

See Also:

DatedCollection.containsThroughout(java.lang.Object, D, D)

containsThroughout

public boolean containsThroughout(java.lang.Object value,
                                  D from,
                                  D to)

Returns true if this dated collection contains the specified element throughout the specified date range.

Specified by:

containsThroughout in interface DatedCollection<E,D>

Overrides:

containsThroughout in class AbstractDatedCollection<E,D>

Parameters:

value - element whose presence is to be tested

from - starting date (inclusive) at which containment should be tested

to - ending date (exclusive) at which containment should be tested

Returns:

true if this dated collection contains the specified element throughout the specified date range

Throws:

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

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

See Also:

DatedCollection.contains(java.lang.Object, D), DatedCollection.excludesThroughout(java.lang.Object, D, D)

dateIterator

public DateIterator<D> dateIterator(D at)

Description copied from interface: DatedObject

Returns an iterator of the date ranges of when this dated object has changed, starting at the range that contains the specified date. Throughout a range returned by the iterator, the state of the dated object must be the same. Also, the states of the dated object must be different in two consecutive ranges returned by the iterator. There are no gaps in the ranges returned by the iterator. That is, if a previous date range exists, then a call to nextFrom returns the same date as previousTo. Passing null as the argument will return an iterator positioned at the beginning of the sequence.

Specified by:

dateIterator in interface DatedObject<D>

Specified by:

dateIterator in class AbstractDatedCollection<E,D>

Parameters:

at - date to position the iteration

Returns:

an iterator of the dates of when this dated object has changed, positioned immediately before the date range that contains the specified date

excludesThroughout

public boolean excludesThroughout(java.lang.Object value,
                                  D from,
                                  D to)

Returns true if this dated collection does not contain the specified element at any date within the specified date range.

Specified by:

excludesThroughout in interface DatedCollection<E,D>

Overrides:

excludesThroughout in class AbstractDatedCollection<E,D>

Parameters:

value - element whose presence is to be tested

from - starting date (inclusive) at which exclusion should be tested

to - ending date (exclusive) at which exclusion should be tested

Returns:

true if this dated collection does not contain value at any date between from and to

Throws:

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

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

See Also:

DatedCollection.containsThroughout(java.lang.Object, D, D)

hasSizeThroughout

public boolean hasSizeThroughout(int size,
                                 D from,
                                 D to)

Returns true if the number of elements in this dated collection is greater than or equal to the specified size throughout the specified date range.

Specified by:

hasSizeThroughout in interface DatedCollection<E,D>

Overrides:

hasSizeThroughout in class AbstractDatedCollection<E,D>

Parameters:

size - number of elements in question

from - starting date (inclusive) at which the size is to be compared

to - ending date (exclusive) at which the size is to be compared

Returns:

true if this dated collection has at least the specified size throughout the specified date range.

Throws:

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

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

See Also:

DatedCollection.size(D), DatedCollection.isEmptyThroughout(D, D)

isEmpty

public boolean isEmpty(D at)

Returns true if this dated collection contains no elements on the specified date.

Specified by:

isEmpty in interface DatedCollection<E,D>

Overrides:

isEmpty in class AbstractDatedCollection<E,D>

Parameters:

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

Returns:

true if this dated collection contains no elements on the specified date

Throws:

java.lang.NullPointerException - if at is null

isEmptyThroughout

public boolean isEmptyThroughout(D from,
                                 D to)

Returns true if this dated collection contains no elements throughout the specified date range.

Specified by:

isEmptyThroughout in interface DatedCollection<E,D>

Overrides:

isEmptyThroughout in class AbstractDatedCollection<E,D>

Parameters:

from - starting date (inclusive) at which this dated collection is to be queried

to - ending date (exclusive) at which this dated collection is to be queried

Returns:

true if this dated collection contains no elements throughout the specified date range.

Throws:

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

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

See Also:

DatedCollection.isEmpty(D)

iterator

public Iterator<E,D> iterator(D at)

Returns an iterator over the elements of this dated collection at the specified date. The returned iterator will always throw an UnsupportedOperationException in its remove method because a date range is required to remove an element from this dated collection.

Specified by:

iterator in interface DatedCollection<E,D>

Specified by:

iterator in class AbstractDatedCollection<E,D>

Parameters:

at - date at which to iterate through the elements

Returns:

an iterator over the elements of this dated collection at the specified date.

Throws:

java.lang.NullPointerException - if at is null

remove

public Dates<D> remove(java.lang.Object value,
                       D from,
                       D to)

Removes an instance of the specified element from this dated collection for the specified date range.

Specified by:

remove in interface DatedCollection<E,D>

Overrides:

remove in class AbstractDatedCollection<E,D>

Parameters:

value - element to remove

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

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

Returns:

a series of date ranges indicating when the removal changed this dated collection

Throws:

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

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

See Also:

DatedCollection.add(E, D, D)

size

public int size(D at)

Returns the number of elements in this dated collection at the specified date.

Specified by:

size in interface DatedCollection<E,D>

Overrides:

size in class AbstractDatedCollection<E,D>

Parameters:

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

Returns:

the number of elements on the specified date

Throws:

java.lang.NullPointerException - if at is null

See Also:

DatedCollection.hasSizeThroughout(int, D, D)