kodkod.util.ints
Interface SparseSequence<V>

All Superinterfaces:
java.lang.Iterable<IndexedEntry<V>>
All Known Implementing Classes:
AbstractSparseSequence, ArraySequence, HomogenousSequence, RangeSequence, TreeSequence

public interface SparseSequence<V>
extends java.lang.Iterable<IndexedEntry<V>>

Represents a sparse sequence -- a sequence whose indices are not necessarily contiguous. For example, a sparse sequence can have elements at indices 10, 2121, and 3000, without having any elements in between. This specification of sparse sequences also supports negative indeces. Formally, the following methods specify a partial function from integers to values of type V.

Sequence implementations are not required to support mutation. All mutating operations are optional and may throw an UnsupportedOperationException.

Author:
Emina Torlak
specfield:
entries: int -> lone V

Method Summary
 IndexedEntry<V> ceil(int index)
          If an entry for the given index exists, it is returned.
 void clear()
          Removes all entries from this sequences.
 SparseSequence<V> clone()
          Returns a copy of this sparse sequence.
 boolean contains(java.lang.Object value)
          Returns true if this sequence has an entry with the given value; otherwise returns false.
 boolean containsIndex(int index)
          Returns true if this sparse sequence has an entry for the given index; otherwise returns false.
 boolean equals(java.lang.Object o)
          Compares the specified object with this sequence for equality.
 IndexedEntry<V> first()
          Returns the entry with the smallest index.
 IndexedEntry<V> floor(int index)
          If an entry for the given index exists, it is returned.
 V get(int index)
          Returns the value to which this sequence maps the given index.
 int hashCode()
          Returns the hash code value for this sparse sequence.
 IntSet indices()
          Returns the set of all indices mapped by this sparse sequence.
 boolean isEmpty()
          Returns true if this sequence is empty; otherwise returns false.
 java.util.Iterator<IndexedEntry<V>> iterator()
          Returns an iterator over the entries in this sequence in the ascending order of indeces, starting at this.first().
 java.util.Iterator<IndexedEntry<V>> iterator(int from, int to)
          Returns an iterator over the entries in this sequence, whose indeces are between from and to.
 IndexedEntry<V> last()
          Returns the entry with the largest index.
 V put(int index, V value)
          Puts the given value at the specified index.
 void putAll(SparseSequence<? extends V> s)
          Copies all of the entries from the specified sparse sequence to this sequence.
 V remove(int index)
          Removes the entry with the given index, if it exists, and returns the value previously stored at the index.
 int size()
          Returns the number of entries in this sequence.
 java.util.Collection<V> values()
          Returns a Collection view of the values stored in this sequence.
 

Method Detail

size

int size()
Returns the number of entries in this sequence.

Returns:
#this.entries

isEmpty

boolean isEmpty()
Returns true if this sequence is empty; otherwise returns false.

Returns:
no this.entries

clear

void clear()
Removes all entries from this sequences.

effects:
no this.entries'

put

V put(int index,
      V value)
Puts the given value at the specified index. If the sequence already mapped the index to a value, the previous value is replaced with the new one and returned.

Returns:
this.entries[index]
Throws:
java.lang.IndexOutOfBoundsException - - the given index is not valid for this sequence.
java.lang.IllegalArgumentException - - the given value cannot be stored in this sequence.
effects:
this.entries' = this.entries + index->value

putAll

void putAll(SparseSequence<? extends V> s)
Copies all of the entries from the specified sparse sequence to this sequence. The effect of this call is equivalent to that of calling put(e.index, e.value) on this sequence once for each entry e in the specified sequence.

Throws:
java.lang.IndexOutOfBoundsException - - s contains indeces that are not valid for this sequence.
java.lang.IllegalArgumentException - - s contains a value that cannot be stored in this sequence.
effects:
this.entries' = this.entries ++ s.entries

get

V get(int index)
Returns the value to which this sequence maps the given index. If the index is not mapped, null is returned.

Returns:
this.entries[index]

remove

V remove(int index)
Removes the entry with the given index, if it exists, and returns the value previously stored at the index. If the sequence had no previous mapping for the index, null is returned.

Returns:
this.entries[index]
effects:
this.entries' = this.entries - index->E

containsIndex

boolean containsIndex(int index)
Returns true if this sparse sequence has an entry for the given index; otherwise returns false.

Returns:
some this.entries[index]

indices

IntSet indices()
Returns the set of all indices mapped by this sparse sequence. The returned set supports removal iff this is not an unmodifiable sparse sequence. The returned set may be uncloneable.

Returns:
{s: IntSet | s.ints = this.entries.V}

contains

boolean contains(java.lang.Object value)
Returns true if this sequence has an entry with the given value; otherwise returns false.

Returns:
some this.entries.value

values

java.util.Collection<V> values()
Returns a Collection view of the values stored in this sequence. The returned collection supports removal iff this is not an unmodifiable sparse sequence.

Returns:
{c: Collection | c.size()=this.size() && all v: V | c.contains(v) <=> this.contains(v) }

iterator

java.util.Iterator<IndexedEntry<V>> iterator()
Returns an iterator over the entries in this sequence in the ascending order of indeces, starting at this.first().

Specified by:
iterator in interface java.lang.Iterable<IndexedEntry<V>>
Returns:
an iterator over this.entries starting at the entry with the smallest index

iterator

java.util.Iterator<IndexedEntry<V>> iterator(int from,
                                             int to)
Returns an iterator over the entries in this sequence, whose indeces are between from and to. If from < to, the entries are returned in the ascending order of indeces. Otherwise, they are returned in the descending order of indeces.

Returns:
an iterator over the entries in this sequence whose indeces are between from and to. Formally, if from < to, then the first and last entries returned by the iterator are this.ceil(from) and this.floor(to). Otherwise, they are this.floor(from) and this.ceil(to).

first

IndexedEntry<V> first()
Returns the entry with the smallest index. If the sequence is empty, returns null.

Returns:
{e: IndexedEntry | e.index = min(this.entries.E) && e.value = this.entries[e.index] }

last

IndexedEntry<V> last()
Returns the entry with the largest index. If the sequence is empty, returns null.

Returns:
{e: IndexedEntry | e.index = max(this.entries.E) && e.value = this.entries[e.index] }

ceil

IndexedEntry<V> ceil(int index)
If an entry for the given index exists, it is returned. Otherwise, successor(index) is returned.

Returns:
this.containsIndex(index) => {e: IndexedEntry | e.index = index && e.value = this.entries[index] }, successor(index)

floor

IndexedEntry<V> floor(int index)
If an entry for the given index exists, it is returned. Otherwise, predecessor(index) is returned.

Returns:
this.containsIndex(index) => {e: IndexedEntry | e.index = index && e.value = this.entries[index] }, predecessor(index)

equals

boolean equals(java.lang.Object o)
Compares the specified object with this sequence for equality. Returns true if the given object is also a sparse sequence and the two sequences have the same entries. More formally, two sequences t1 and t2 have the the same entries if they represent the same function from integers to values: i.e. t1.entries = t2.entries. This ensures that the equals method works properly across different implementations of the SparseSequence interface.

Overrides:
equals in class java.lang.Object
Returns:
o in SparseSequence && o.entries = this.entries

hashCode

int hashCode()
Returns the hash code value for this sparse sequence. A hash function for a sparse sequence must ensure that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two sequences t1 and t2, as required by the general contract of Object.hashCode.

Overrides:
hashCode in class java.lang.Object
Returns:
hash code for this sparse sequence

clone

SparseSequence<V> clone()
                        throws java.lang.CloneNotSupportedException
Returns a copy of this sparse sequence. The copy is independent of this sequence unless this is a singleton or immutable, in which case clone() may return this. An implementing class that does not support cloning may throw a CloneNotSupportedException.

Returns:
a copy of this sparse sequence.
Throws:
java.lang.CloneNotSupportedException - - this is not cloneable