JML

org.jmlspecs.models
Class JMLEqualsSequence

java.lang.Object
  extended byorg.jmlspecs.models.JMLEqualsSequence
All Implemented Interfaces:
Cloneable, JMLCollection, JMLType, Serializable

public class JMLEqualsSequence
extends Object
implements JMLCollection

Sequences of objects. This type uses ".equals" to compare elements, and does not clone elements that are passed into and returned from the sequence's methods.

The informal model for a JMLEqualsSequence is a finite mathematical sequence of elements (of type Object). In some examples, we will write <a,b,c> for a mathematical sequence of length 3, containing elements a, b, and c. Elements of sequences are "indexed" from 0, so the length of a sequence is always 1 more than the index of the last element in the sequence.

Version:
$Revision: 1.80 $
Author:
Gary T. Leavens, Albert L. Baker
See Also:
JMLCollection, JMLType, JMLObjectSequence, JMLValueSequence, JMLEqualsSequenceEnumerator

Field Summary
protected  BigInteger _length
          This sequence's length.
static JMLEqualsSequence EMPTY
          The empty JMLEqualsSequence.
private static String IS_NOT_FOUND
           
private static String ITEM_PREFIX
           
protected  JMLListEqualsNode theSeq
          An equational specification of the properties of sequences.
private static String TOO_BIG_TO_INSERT
           
 
Constructor Summary
  JMLEqualsSequence()
          Initialize this to be the empty sequence.
  JMLEqualsSequence(Object e)
          Initialize this to be the sequence containing just the given element.
protected JMLEqualsSequence(JMLListEqualsNode ls, int len)
          Initialize this sequence based on the given representation.
 
Method Summary
 Object clone()
          Return a clone of this object.
 JMLEqualsSequence concat(JMLEqualsSequence s2)
          Return a sequence that is the concatenation of this with the given sequence.
 boolean containsAll(Collection c)
          Tell whether, for each element in the given collection, there is a ".equals" element in this sequence.
static JMLEqualsSequence convertFrom(Object[] a)
          Return the sequence containing all the elements in the given array in the same order as the elements appear in the array.
static JMLEqualsSequence convertFrom(Object[] a, int size)
          Return the sequence containing the first 'size' elements in the given array in the same order as the elements appear in the array.
static JMLEqualsSequence convertFrom(Collection c)
          Return the sequence containing all the object in the given collection in the same order as the elements appear in the collection.
static JMLEqualsSequence convertFrom(JMLCollection c)
          Return the sequence containing all the object in the given JMLCollection in the same order as the elements appear in the collection.
 int count(Object item)
          Tells the number of times a given element occurs in the sequence.
 JMLEqualsSequenceEnumerator elements()
          Return a enumerator for this.
 boolean equals(Object obj)
          Test whether this object's value is equal to the given argument.
 Object first()
          Return the first element in this sequence.
 Object get(int i)
          Return the element at the given zero-based index; a synonym for itemAt(int).
 boolean has(Object elem)
          Tells whether the given element is ".equals" to an element in the sequence.
 int hashCode()
          Return a hash code for this object.
 JMLEqualsSequence header()
          Return a sequence containing all but the last element in this.
 int indexOf(Object item)
          Return the zero-based index of the first occurrence of the given element in the sequence, if there is one
 JMLEqualsSequence insertAfterIndex(int afterThisOne, Object item)
          Return a sequence like this, but with item put immediately after the given index.
 JMLEqualsSequence insertBack(Object item)
          Return a sequence like this, but with the given item put an the end.
 JMLEqualsSequence insertBeforeIndex(int beforeThisOne, Object item)
          Return a sequence like this, but with item put immediately before the given index.
 JMLEqualsSequence insertFront(Object item)
          Return a sequence like this, but with the given item put an the front.
 int int_length()
          Tells the number of elements in the sequence; a synonym for #size.
 int int_size()
          Tells the number of elements in the sequence; a synonym for #length.
 boolean isDeletionFrom(JMLEqualsSequence s2, Object elem)
          Tells whether this sequence is the result of deleting the given element once from the given sequence.
 boolean isEmpty()
          Tells whether this sequence is empty.
 boolean isInsertionInto(JMLEqualsSequence s2, Object elem)
          Tells whether this sequence is the result of inserting the given element once into the given sequence.
 boolean isPrefix(JMLEqualsSequence s2)
          Tells whether the elements of the this sequence occur, in order, at the beginning of the given sequence, using ".equals" for comparisons.
 boolean isProperPrefix(JMLEqualsSequence s2)
          Tells whether this sequence is shorter than the given sequence, and also if the elements of this sequence occur, in order, at the beginning of the given sequence, using ".equals" for comparisons.
 boolean isProperSubsequence(JMLEqualsSequence s2)
          Tells whether this sequence is strictly shorter than the given sequence and a subsequence of it.
 boolean isProperSuffix(JMLEqualsSequence s2)
          Tells whether the this sequence is shorter than the given object, and also if the elements of this sequence occur, in order, at the end of the given sequence, using ".equals" for comparisons.
 boolean isProperSupersequence(JMLEqualsSequence s2)
          Tells whether the given sequence is both longer than and a supersequence of this sequence.
 boolean isSubsequence(JMLEqualsSequence s2)
          Tells whether this sequence is a subsequence of the given sequence.
 boolean isSuffix(JMLEqualsSequence s2)
          Tells whether the elements of this sequence occur, in order, at the end of the given sequence, using ".equals" for comparisons.
 boolean isSupersequence(JMLEqualsSequence s2)
          Tells whether the given sequence is a supersequence of this sequence.
 Object itemAt(int i)
          Return the element at the given zero-based index.
 JMLIterator iterator()
          Returns an iterator over this sequence.
 Object last()
          Return the last element in this sequence.
 JMLEqualsSequence prefix(int n)
          Return a sequence containing the first n elements in this sequence.
 JMLEqualsSequence removeItemAt(int index)
          Return a sequence like this, but without the element at the given zero-based index.
 JMLEqualsSequence removePrefix(int n)
          Return a sequence containing all but the first n elements in this.
 JMLEqualsSequence replaceItemAt(int index, Object item)
          Return a sequence like this, but with item replacing the element at the given zero-based index.
 JMLEqualsSequence reverse()
          Return a sequence that is the reverse of this sequence.
static JMLEqualsSequence singleton(Object e)
          Return the singleton sequence containing the given element.
 JMLEqualsSequence subsequence(int from, int to)
          Returns a subsequence of this containing the elements beginning with index from (inclusive) and ending with index to (exclusive).
 Object[] toArray()
          Return a new array containing all the elements of this in order.
 JMLEqualsBag toBag()
          Return a new JMLEqualsBag containing all the elements of this.
 JMLEqualsSet toSet()
          Return a new JMLEqualsSet containing all the elements of this.
 String toString()
          Return a string representation of this object.
 JMLEqualsSequence trailer()
          Return a sequence containing all but the first element in this.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

theSeq

protected final JMLListEqualsNode theSeq
An equational specification of the properties of sequences. The list representing this sequence's elements, in order.


_length

protected final BigInteger _length
This sequence's length.


EMPTY

public static final JMLEqualsSequence EMPTY
The empty JMLEqualsSequence.

See Also:
JMLEqualsSequence()

ITEM_PREFIX

private static final String ITEM_PREFIX

IS_NOT_FOUND

private static final String IS_NOT_FOUND

TOO_BIG_TO_INSERT

private static final String TOO_BIG_TO_INSERT
Constructor Detail

JMLEqualsSequence

public JMLEqualsSequence()
Initialize this to be the empty sequence.

See Also:
EMPTY

JMLEqualsSequence

public JMLEqualsSequence(Object e)
Initialize this to be the sequence containing just the given element.

Parameters:
e - the element that is the first element in this sequence.
See Also:
singleton(java.lang.Object)

JMLEqualsSequence

protected JMLEqualsSequence(JMLListEqualsNode ls,
                            int len)
Initialize this sequence based on the given representation. Initialize this sequence based on the given representation.

Method Detail

singleton

public static JMLEqualsSequence singleton(Object e)
Return the singleton sequence containing the given element.

See Also:
JMLEqualsSequence(Object)

convertFrom

public static JMLEqualsSequence convertFrom(Object[] a)
Return the sequence containing all the elements in the given array in the same order as the elements appear in the array.


convertFrom

public static JMLEqualsSequence convertFrom(Object[] a,
                                            int size)
Return the sequence containing the first 'size' elements in the given array in the same order as the elements appear in the array.


convertFrom

public static JMLEqualsSequence convertFrom(Collection c)
                                     throws ClassCastException
Return the sequence containing all the object in the given collection in the same order as the elements appear in the collection.

Throws:
ClassCastException - if some element in c is not an instance of Object.
See Also:
containsAll(java.util.Collection)

convertFrom

public static JMLEqualsSequence convertFrom(JMLCollection c)
                                     throws ClassCastException
Return the sequence containing all the object in the given JMLCollection in the same order as the elements appear in the collection.

Throws:
ClassCastException - if some element in c is not an instance of Object.

itemAt

public Object itemAt(int i)
              throws JMLSequenceException
Return the element at the given zero-based index.

Parameters:
i - the zero-based index into the sequence.
Throws:
JMLSequenceException - if the index oBiI is out of range.
JMLSequenceException - if the index i is out of range.
See Also:
get(int), has(Object), Return the element at the given zero-based index., get(int), has(Object), count(Object), #itemAt(\bigint)

get

public Object get(int i)
           throws IndexOutOfBoundsException
Return the element at the given zero-based index; a synonym for itemAt(int).

Parameters:
i - the zero-based index into the sequence.
Throws:
IndexOutOfBoundsException - if the index i is out of range.
IndexOutOfBoundsException - if the index i is out of range.
See Also:
Return the element at the given zero-based index; a synonym for {@link #itemAt}., itemAt(int)

int_size

public int int_size()
Tells the number of elements in the sequence; a synonym for #length.

Specified by:
int_size in interface JMLCollection
See Also:
#length(), Tells the number of elements in the sequence; a synonym for {@link #length}., #size(), Tells the number of elements in the sequence; a synonym for {@link #length}., #length(), isEmpty()

int_length

public int int_length()
Tells the number of elements in the sequence; a synonym for #size.

See Also:
int_size()

count

public int count(Object item)
Tells the number of times a given element occurs in the sequence.

See Also:
has(Object), Tells the number of times a given element occurs in the sequence., has(Object), itemAt(int)

has

public boolean has(Object elem)
Tells whether the given element is ".equals" to an element in the sequence.

Specified by:
has in interface JMLCollection
See Also:
count(Object)

containsAll

public boolean containsAll(Collection c)
Tell whether, for each element in the given collection, there is a ".equals" element in this sequence.

Parameters:
c - the collection whose elements are sought.

isPrefix

public boolean isPrefix(JMLEqualsSequence s2)
Tells whether the elements of the this sequence occur, in order, at the beginning of the given sequence, using ".equals" for comparisons.

See Also:
isProperPrefix(org.jmlspecs.models.JMLEqualsSequence), isSuffix(org.jmlspecs.models.JMLEqualsSequence)

isProperPrefix

public boolean isProperPrefix(JMLEqualsSequence s2)
Tells whether this sequence is shorter than the given sequence, and also if the elements of this sequence occur, in order, at the beginning of the given sequence, using ".equals" for comparisons.

See Also:
isPrefix(org.jmlspecs.models.JMLEqualsSequence), isProperSuffix(org.jmlspecs.models.JMLEqualsSequence)

isSuffix

public boolean isSuffix(JMLEqualsSequence s2)
Tells whether the elements of this sequence occur, in order, at the end of the given sequence, using ".equals" for comparisons.

See Also:
isProperSuffix(org.jmlspecs.models.JMLEqualsSequence), isPrefix(org.jmlspecs.models.JMLEqualsSequence)

isProperSuffix

public boolean isProperSuffix(JMLEqualsSequence s2)
Tells whether the this sequence is shorter than the given object, and also if the elements of this sequence occur, in order, at the end of the given sequence, using ".equals" for comparisons.

See Also:
isSuffix(org.jmlspecs.models.JMLEqualsSequence), isProperPrefix(org.jmlspecs.models.JMLEqualsSequence)

equals

public boolean equals(Object obj)
Test whether this object's value is equal to the given argument.

Specified by:
equals in interface JMLType
Overrides:
equals in class Object
See Also:
isSuffix(org.jmlspecs.models.JMLEqualsSequence), int_size()

hashCode

public int hashCode()
Return a hash code for this object.

Specified by:
hashCode in interface JMLType
Overrides:
hashCode in class Object

isEmpty

public boolean isEmpty()
Tells whether this sequence is empty.

See Also:
int_size(), int_length()

indexOf

public int indexOf(Object item)
            throws JMLSequenceException
Return the zero-based index of the first occurrence of the given element in the sequence, if there is one

Parameters:
item - the Object sought in this.
Returns:
the first index at which item occurs.
Throws:
JMLSequenceException - if item is not a member of the sequence.
JMLSequenceException - if item is not a member of the sequence.
See Also:
Return the zero-based index of the first occurrence of the given element in the sequence, if there is one, itemAt(int)

first

public Object first()
             throws JMLSequenceException
Return the first element in this sequence.

Throws:
JMLSequenceException - if the sequence is empty.
See Also:
itemAt(int), last(), trailer(), header()

last

public Object last()
            throws JMLSequenceException
Return the last element in this sequence.

Throws:
JMLSequenceException - if the sequence is empty.
See Also:
itemAt(int), first(), header(), trailer()

isSubsequence

public boolean isSubsequence(JMLEqualsSequence s2)
Tells whether this sequence is a subsequence of the given sequence.

Parameters:
s2 - the sequence to search for within this sequence.
Returns:
whether the elements of this occur (in order) within s2.
See Also:
isProperSubsequence(org.jmlspecs.models.JMLEqualsSequence), isSupersequence(org.jmlspecs.models.JMLEqualsSequence)

isProperSubsequence

public boolean isProperSubsequence(JMLEqualsSequence s2)
Tells whether this sequence is strictly shorter than the given sequence and a subsequence of it.

Parameters:
s2 - the sequence to search for within this sequence.
Returns:
whether the elements of s2 occur (in order) within this.
See Also:
isSubsequence(org.jmlspecs.models.JMLEqualsSequence), isProperSupersequence(org.jmlspecs.models.JMLEqualsSequence)

isSupersequence

public boolean isSupersequence(JMLEqualsSequence s2)
Tells whether the given sequence is a supersequence of this sequence.

Parameters:
s2 - the sequence to search within for this sequence.
Returns:
whether the elements of this occur (in order) within s2.
See Also:
isProperSubsequence(org.jmlspecs.models.JMLEqualsSequence), isSubsequence(org.jmlspecs.models.JMLEqualsSequence)

isProperSupersequence

public boolean isProperSupersequence(JMLEqualsSequence s2)
Tells whether the given sequence is both longer than and a supersequence of this sequence.

Parameters:
s2 - the sequence to search within for this sequence.
Returns:
whether the elements of this occur (in order) within s2.
See Also:
isSupersequence(org.jmlspecs.models.JMLEqualsSequence), isProperSubsequence(org.jmlspecs.models.JMLEqualsSequence)

isInsertionInto

public boolean isInsertionInto(JMLEqualsSequence s2,
                               Object elem)
Tells whether this sequence is the result of inserting the given element once into the given sequence. That is, this sequence is exactly one element longer than the given sequence, and its elements are in the same order, except for the insertion of the given element.

Parameters:
s2 - the shorter sequence, which we see if the elem is inserted into
elem - the given element
Returns:
whether the elements of s2 occur in order in this sequence, with the insertion of elem somewhere.
See Also:
isDeletionFrom(org.jmlspecs.models.JMLEqualsSequence, java.lang.Object), isProperSupersequence(org.jmlspecs.models.JMLEqualsSequence), isProperSubsequence(org.jmlspecs.models.JMLEqualsSequence), subsequence(int, int)

isDeletionFrom

public boolean isDeletionFrom(JMLEqualsSequence s2,
                              Object elem)
Tells whether this sequence is the result of deleting the given element once from the given sequence. That is, this sequence is exactly one element shorter than the given sequence, and its elements are in the same order, except for the deletion of the given element from the given sequence.

Parameters:
s2 - the longer sequence, in which we see if the elem is deleted from
elem - the given element
Returns:
whether the elements of s2 occur in order in this sequence, with the deletion of elem somewhere.
See Also:
isInsertionInto(org.jmlspecs.models.JMLEqualsSequence, java.lang.Object), isProperSupersequence(org.jmlspecs.models.JMLEqualsSequence), isProperSubsequence(org.jmlspecs.models.JMLEqualsSequence), subsequence(int, int)

clone

public Object clone()
Return a clone of this object. This method does not clone the elements of the sequence.

Specified by:
clone in interface JMLType
Overrides:
clone in class Object

prefix

public JMLEqualsSequence prefix(int n)
                         throws JMLSequenceException
Return a sequence containing the first n elements in this sequence.

Parameters:
n - the number of elements in the result.
Throws:
JMLSequenceException - if n is negative or greater than the length of the sequence.
JMLSequenceException - if n is negative or greater than the length of the sequence.
See Also:
trailer(), removePrefix(int), Return a sequence containing the first n elements in this sequence., trailer(), removePrefix(int), subsequence(int, int)

removePrefix

public JMLEqualsSequence removePrefix(int n)
                               throws JMLSequenceException
Return a sequence containing all but the first n elements in this.

Parameters:
n - the number of elements to remove
Throws:
JMLSequenceException - if n is negative or greater than the length of the sequence.
JMLSequenceException - if n is negative or greater than the length of the sequence.
See Also:
header(), prefix(int), Return a sequence containing all but the first n elements in this., header(), prefix(int), subsequence(int, int)

concat

public JMLEqualsSequence concat(JMLEqualsSequence s2)
Return a sequence that is the concatenation of this with the given sequence.

Parameters:
s2 - the sequence to place at the end of this sequence in the result.
Returns:
the concatenation of this sequence and s2.

reverse

public JMLEqualsSequence reverse()
Return a sequence that is the reverse of this sequence.

Returns:
the reverse of this sequence.

removeItemAt

public JMLEqualsSequence removeItemAt(int index)
                               throws JMLSequenceException
Return a sequence like this, but without the element at the given zero-based index.

Parameters:
index - the zero-based index into the sequence.
Throws:
JMLSequenceException - if the index is out of range.
JMLSequenceException - if the index is out of range.
See Also:
itemAt(int), removeItemAt(int), prefix(int), removePrefix(int), subsequence(int, int), Return a sequence like this, but without the element at the given zero-based index., itemAt(int), removeItemAt(int), prefix(int), removePrefix(int), subsequence(int, int), concat(org.jmlspecs.models.JMLEqualsSequence)

replaceItemAt

public JMLEqualsSequence replaceItemAt(int index,
                                       Object item)
                                throws JMLSequenceException
Return a sequence like this, but with item replacing the element at the given zero-based index.

Parameters:
index - the zero-based index into the sequence.
item - the item to put at index index
Throws:
JMLSequenceException - if the index is out of range.
JMLSequenceException - if the index is out of range.
See Also:
itemAt(int), Return a sequence like this, but with item replacing the element at the given zero-based index., itemAt(int), replaceItemAt(int, java.lang.Object)

header

public JMLEqualsSequence header()
                         throws JMLSequenceException
Return a sequence containing all but the last element in this.

Throws:
JMLSequenceException - if this is empty.
See Also:
prefix(int), first(), last(), trailer(), subsequence(int, int)

trailer

public JMLEqualsSequence trailer()
                          throws JMLSequenceException
Return a sequence containing all but the first element in this.

Throws:
JMLSequenceException - if this is empty.
See Also:
removePrefix(int), last(), first(), header(), subsequence(int, int)

insertAfterIndex

public JMLEqualsSequence insertAfterIndex(int afterThisOne,
                                          Object item)
                                   throws JMLSequenceException,
                                          IllegalStateException
Return a sequence like this, but with item put immediately after the given index.

Parameters:
afterThisOne - a zero-based index into the sequence, or -1.
item - the item to put after index afterThisOne
Returns:
if the index is in range
Throws:
JMLSequenceException - if the index is out of range.
JMLSequenceException - if the index is out of range.
IllegalStateException
See Also:
insertBeforeIndex(int, java.lang.Object), insertFront(java.lang.Object), insertBack(java.lang.Object), Return a sequence like this, but with item put immediately after the given index., insertBeforeIndex(int, java.lang.Object), insertFront(java.lang.Object), insertBack(java.lang.Object), removeItemAt(int)

insertBeforeIndex

public JMLEqualsSequence insertBeforeIndex(int beforeThisOne,
                                           Object item)
                                    throws JMLSequenceException,
                                           IllegalStateException
Return a sequence like this, but with item put immediately before the given index.

Parameters:
beforeThisOne - a zero-based index into the sequence, or the length of this.
item - the item to put before index beforeThisOne
Returns:
if the index is in range
Throws:
JMLSequenceException - if the index is out of range.
JMLSequenceException - if the index is out of range.
IllegalStateException
See Also:
insertAfterIndex(int, java.lang.Object), insertFront(java.lang.Object), insertBack(java.lang.Object), Return a sequence like this, but with item put immediately before the given index., insertAfterIndex(int, java.lang.Object), insertFront(java.lang.Object), insertBack(java.lang.Object), removeItemAt(int)

insertBack

public JMLEqualsSequence insertBack(Object item)
                             throws IllegalStateException
Return a sequence like this, but with the given item put an the end.

Parameters:
item - the item to put at the end of the result.
Returns:
a sequence the elements of this sequence followed by item.
Throws:
IllegalStateException
See Also:
insertAfterIndex(int, java.lang.Object), insertBeforeIndex(int, java.lang.Object), insertFront(java.lang.Object), removeItemAt(int), header(), last()

insertFront

public JMLEqualsSequence insertFront(Object item)
                              throws IllegalStateException
Return a sequence like this, but with the given item put an the front.

Parameters:
item - the item to put at the front of the result.
Returns:
a sequence with item followed by the elements of this sequence.
Throws:
IllegalStateException
See Also:
insertAfterIndex(int, java.lang.Object), insertBeforeIndex(int, java.lang.Object), insertBack(java.lang.Object), removeItemAt(int), trailer(), first()

subsequence

public JMLEqualsSequence subsequence(int from,
                                     int to)
                              throws JMLSequenceException
Returns a subsequence of this containing the elements beginning with index from (inclusive) and ending with index to (exclusive).

Parameters:
from - the inclusive, zero-based element of the first element in the subsequence.
to - the zero-based element of the first element that should not be in the subsequence.
Throws:
JMLSequenceException - if (from < 0 or from > to or to > length of this.
JMLSequenceException - if (from < 0 or from > to or to > length of this.
See Also:
prefix(int), removePrefix(int), header(), trailer(), Returns a subsequence of this containing the elements beginning with index from (inclusive) and ending with index to (exclusive)., prefix(int), removePrefix(int), header(), trailer(), concat(org.jmlspecs.models.JMLEqualsSequence)

toBag

public JMLEqualsBag toBag()
Return a new JMLEqualsBag containing all the elements of this.

See Also:
toSet(), toArray()

toSet

public JMLEqualsSet toSet()
Return a new JMLEqualsSet containing all the elements of this.

See Also:
toBag(), toArray()

toArray

public Object[] toArray()
Return a new array containing all the elements of this in order.

See Also:
toSet(), toBag()

elements

public JMLEqualsSequenceEnumerator elements()
Return a enumerator for this.

See Also:
iterator(), #itemAt()

iterator

public JMLIterator iterator()
Returns an iterator over this sequence.

Specified by:
iterator in interface JMLCollection
See Also:
elements()

toString

public String toString()
Return a string representation of this object.

Overrides:
toString in class Object

JML

JML is Copyright (C) 1998-2002 by Iowa State University and is distributed under the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This release depends on code from the MultiJava project and is based in part on the Kopi project Copyright (C) 1990-99 DMS Decision Management Systems Ges.m.b.H.