kodkod.util.ints
Class RangeSequence<V>

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

public final class RangeSequence<V>
extends AbstractSparseSequence<V>
implements java.lang.Cloneable

A tree-based sparse sequence implementation. Unlike TreeSequence, this is not a general-purpose sparse sequence implementation. In particular, the entries with consecutive indices and the same value are not stored explicitly. As a result, methods that return an IndexedEntry may re-use the same object. Specifically, the last assertion in the following code snippet may fail.

 // let s be a range sequence abstractly represented as { 0->v, 1->v, 2->v }
 IndexedEntry e1 = s.predecessor(2);
 assert e1.index()==1; // this will work
 IndexedEntry e2 = s.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
 

This implementation is a good choice when the client expects the usage pattern with many consecutive indices mapped to the same value, and when there is no need for entry uniqueness.

Author:
Emina Torlak

Constructor Summary
RangeSequence()
          Constructs an empty RangeSequence.
 
Method Summary
 IndexedEntry<V> ceil(int index)
          Returns the entry whose index is the ceiling of the given index in this sequence.
 void clear()
          Removes all entries from this sequences.
 RangeSequence<V> clone()
          Returns a copy of this sparse sequence.
 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 first element in this sequence, if any.
 IndexedEntry<V> floor(int index)
          Returns the entry whose index is the floor of the given index in this sequence.
 V get(int index)
          Returns the value to which this sequence maps the given index.
 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 last element in this sequence, if any.
 V put(int index, V value)
          Throws an UnsupportedOperationException.
 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
contains, equals, hashCode, indices, isEmpty, iterator, putAll, toString, values
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RangeSequence

public RangeSequence()
Constructs an empty RangeSequence.

effects:
no this.entries'
Method Detail

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.

Specified by:
iterator in interface SparseSequence<V>
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.

Specified by:
size in interface SparseSequence<V>
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)
Throws an UnsupportedOperationException.

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

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.

Specified by:
get in interface SparseSequence<V>
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. This method returns the value of this.iterator(index,index).hasNext(); 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)

first

public IndexedEntry<V> first()
Returns the first element in this sequence, if any. This method first checks that the sequence is not empty, and if not, returns this.iterator().next(); 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 last element in this sequence, if any. This method first checks that the sequence is not empty, and if not, returns this.iterator(Integer.MAX_VALUE, Integer.MIN_VALUE).next(); 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)
Returns the entry whose index is the ceiling of the given index in this sequence. This method calls this.iterator(index, Integer.MAX_VALUE), and if the resulting iterator has a next element returns it. 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)
Returns the entry whose index is the floor of the given index in this sequence. This method calls this.iterator(index, Integer.MIN_VALUE), and if the resulting iterator has a next element returns it. 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 RangeSequence<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()