kodkod.util.ints
Class HomogenousSequence<V>

java.lang.Object
  extended by kodkod.util.ints.AbstractSparseSequence<V>
      extended by kodkod.util.ints.HomogenousSequence<V>
All Implemented Interfaces:
java.lang.Iterable<IndexedEntry<V>>, SparseSequence<V>

public final class HomogenousSequence<V>
extends AbstractSparseSequence<V>

A sparse sequence implementation based on an IntSet. This implementation can be used only when all entries in the sequence map to the same value.

Important Implementation Note: As this implementation does not actually store any indexed entries, the methods first(), last(), ceil(int), and floor(int) may re-use the same IndexedEntry object. For example, suppose that an entry e with e.index = 1 is returned by a call to predecessor(2) on a homogenous sequence h = {<0,v>, <1,v>, <2,v>}. A subsequent call to h.predecessor(1) may return the same object e, with its index set to 0. Hence, the following assertion may fail:

 IndexedEntry e1 = h.predecessor(2);
 assert e1.index()==1; // this will work
 IndexedEntry e2 = h.predecessor(1);
 assert e1.index()==1; // this may fail, as e1 may be == to e2
 

The entries returned by this implementation's AbstractSparseSequence.iterator() are unique to that iterator (but not necessarily independent of each other). For example,

 // let s be a range sequence abstractly represented as { 0->v, 1->v, 2->v }
 Iterator> iter1 = s.iterator();
 IndexedEntry e1 = iter1.next();
 assert e1.index()==0; // this will work
 iter1.next();
 assert e1.index()==0; // this may fail, as the previous call may have changed the state of e1
 Iterator> iter2 = s.iterator();
 IndexedEntry e2 = iter2.next();
 iter1.next();
 assert e2.index()==0; // this will work
 

Author:
Emina Torlak
specfield:
indeces: set int
entries: indeces -> one V

Constructor Summary
HomogenousSequence(SparseSequence<? extends V> seq)
          Constructs a new homogeneous sequence from the provided sequence.
HomogenousSequence(V value)
          Constructs a new homogenous sequence for the given value, backed by a IntTreeSet instance.
HomogenousSequence(V value, IntSet indices)
          Constructs a new homogenous sequence for the given value, backed by the specified intset.
 
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.
 HomogenousSequence<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.
 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.
 IntSet indices()
          Returns the set of all indices mapped by this sparse sequence.
 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.
 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.
 
Methods inherited from class kodkod.util.ints.AbstractSparseSequence
equals, hashCode, isEmpty, iterator, putAll, toString, values
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

HomogenousSequence

public HomogenousSequence(V value)
Constructs a new homogenous sequence for the given value, backed by a IntTreeSet instance.

effects:
this.value' = value && no this.indices'

HomogenousSequence

public HomogenousSequence(V value,
                          IntSet indices)
Constructs a new homogenous sequence for the given value, backed by the specified intset. Any changes to the provided set will be reflected in this sequence, and vice versa. This sequence will be unmodifiable if the given index set is unmodifiable.

effects:
this.value' = value && this.indices' = indices
requires:
indices is cloneable

HomogenousSequence

public HomogenousSequence(SparseSequence<? extends V> seq)
Constructs a new homogeneous sequence from the provided sequence. The returned sequence is backed by a IntTreeSet instance.

Throws:
java.lang.NullPointerException - - seq = null
java.lang.IllegalArgumentException - - seq.isEmpty()
java.lang.IllegalArgumentException - - #seq.entries[int] > 1
effects:
this.value' = seq.entries[int] && this.indices' = seq.indices()
requires:
one seq.entries[int]
Method Detail

indices

public IntSet indices()
Returns the set of all indices mapped by this sparse sequence. The returned set supports removal and addition iff this is not backed by an unmodifiable intset.

Specified by:
indices in interface SparseSequence<V>
Overrides:
indices in class AbstractSparseSequence<V>
Returns:
{s: IntSet | s.ints = this.entries.V}

iterator

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

While the returned iterator i re-uses the same IndexedEntry object, it is not shared with other iterators or other method calls. In particular, no other call except i.next() can change the value of the re-used object.

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).
See Also:
SparseSequence.iterator(int, int)

size

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

Returns:
#this.entries
See Also:
SparseSequence.size()

clear

public void clear()
Removes all entries from this sequences.

Specified by:
clear in interface SparseSequence<V>
Overrides:
clear in class AbstractSparseSequence<V>
See Also:
SparseSequence.clear()
effects:
no this.entries'

put

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

Specified by:
put in interface SparseSequence<V>
Overrides:
put in class AbstractSparseSequence<V>
Returns:
this.entries[index]
Throws:
java.lang.IllegalArgumentException - - this.value != value
See Also:
SparseSequence.put(int, Object)
effects:
this.indices' = this.indices + index
requires:
this.value = value

get

public 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]
See Also:
SparseSequence.get(int)

remove

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

Specified by:
remove in interface SparseSequence<V>
Overrides:
remove in class AbstractSparseSequence<V>
Returns:
this.entries[index]
See Also:
SparseSequence.remove(int)
effects:
this.entries' = this.entries - index->E

containsIndex

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

Specified by:
containsIndex in interface SparseSequence<V>
Overrides:
containsIndex in class AbstractSparseSequence<V>
Returns:
some this.entries[index]
See Also:
SparseSequence.containsIndex(int)

contains

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

Specified by:
contains in interface SparseSequence<V>
Overrides:
contains in class AbstractSparseSequence<V>
Returns:
some this.indices && this.value = value
See Also:
SparseSequence.contains(java.lang.Object)

first

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

Specified by:
first in interface SparseSequence<V>
Overrides:
first in class AbstractSparseSequence<V>
Returns:
{e: IndexedEntry | e.index = min(this.entries.E) && e.value = this.entries[e.index] }
See Also:
SparseSequence.first()

last

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

Specified by:
last in interface SparseSequence<V>
Overrides:
last in class AbstractSparseSequence<V>
Returns:
{e: IndexedEntry | e.index = max(this.entries.E) && e.value = this.entries[e.index] }
See Also:
SparseSequence.last()

ceil

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

Specified by:
ceil in interface SparseSequence<V>
Overrides:
ceil in class AbstractSparseSequence<V>
Returns:
this.containsIndex(index) => {e: IndexedEntry | e.index = index && e.value = this.entries[index] }, successor(index)
See Also:
SparseSequence.ceil(int)

floor

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

Specified by:
floor in interface SparseSequence<V>
Overrides:
floor in class AbstractSparseSequence<V>
Returns:
this.containsIndex(index) => {e: IndexedEntry | e.index = index && e.value = this.entries[index] }, predecessor(index)
See Also:
SparseSequence.floor(int)

clone

public HomogenousSequence<V> clone()
Returns a copy of this sparse sequence. The copy is independent of this sequence.

Specified by:
clone in interface SparseSequence<V>
Overrides:
clone in class AbstractSparseSequence<V>
Returns:
a copy of this sparse sequence.
See Also:
SparseSequence.clone()