gnu.lists
Class AbstractSequence

java.lang.Object
  extended by gnu.lists.AbstractSequence
Direct Known Subclasses:
Buffer, ExtSequence, GapVector, GeneralArray, SimpleVector, SubSequence, TreeList

public abstract class AbstractSequence
extends java.lang.Object

An AbstractSequence is used to implement Sequences, and almost all classes that extend AbstractSequence will implement Sequence. However, AbstractSequence itself does not implement Sequence. This is so we can use AbstractSequence to implement classes that are "sequence-like" (such as multi-dimesnional arrays) but are not Sequences. Additionally, a sequence may have zero or more attributes, which are name-value pairs. A sequence may also have a named "type". These extensions are to support XML functionality - it might be cleaner to moe them to a sub-class of Sequence or some interface. Many of the protected methods in Sequence (such as nextIndex) are only intended to be called from SeqPosition or TreePosition, see those.


Constructor Summary
AbstractSequence()
           
 
Method Summary
 void add(int index, java.lang.Object o)
          See java.util.List.
 boolean add(java.lang.Object o)
          See java.util.Collection.
 boolean addAll(java.util.Collection c)
          See java.util.Collection.
 boolean addAll(int index, java.util.Collection c)
          See java.util.Collection.
protected  int addPos(int ipos, java.lang.Object value)
          Add a value at a specified Pos.
 AbstractSequence append(char c)
           
 AbstractSequence append(java.lang.CharSequence csq)
           
 AbstractSequence append(java.lang.CharSequence csq, int start, int end)
           
 java.lang.Object baseUriOfPos(int pos)
          Return of the base-uri property, if known, of the node at pos.
 void clear()
           
static int compare(AbstractSequence seq1, int pos1, AbstractSequence seq2, int pos2)
          This is used for the XML concept of "document order".
 int compare(int ipos1, int ipos2)
          Compare two positions, and indicate their relative order.
 int compare(SeqPosition i1, SeqPosition i2)
           
 void consume(Consumer out)
           
 boolean consumeNext(int ipos, Consumer out)
          Copy an element specified by a position pair to a Consumer.
 void consumePosRange(int iposStart, int iposEnd, Consumer out)
           
 boolean contains(java.lang.Object o)
          See java.util.List.
 boolean containsAll(java.util.Collection c)
          See java.util.List.
 int copyPos(int ipos)
          Make a copy of a position int.
abstract  int createPos(int index, boolean isAfter)
          Generate a position at a given index.
 int createRelativePos(int pos, int delta, boolean isAfter)
           
 java.util.Enumeration elements()
           
 int endPos()
           
 boolean equals(int ipos1, int ipos2)
          Compare two positions, and indicate if they are the same position.
 boolean equals(java.lang.Object o)
           
 void fill(int fromIndex, int toIndex, java.lang.Object value)
           
 void fill(java.lang.Object value)
           
 void fillPosRange(int fromPos, int toPos, java.lang.Object value)
           
 int firstAttributePos(int ipos)
          Like firstChildPos.
 int firstChildPos(int ipos)
          Get position before first child (of the element following position).
protected  int fromEndIndex(int ipos)
           
abstract  java.lang.Object get(int index)
          See java.util.List.
 java.lang.Object get(int[] indexes)
           
 java.lang.Object getAttribute(int index)
           
 int getAttributeLength()
           
protected  int getContainingSequenceSize(int ipos)
          Get the size of the (sub-) sequence containing a given position.
 int getEffectiveIndex(int[] indexes)
           
protected  int getIndexDifference(int ipos1, int ipos0)
          Get offset of (ipos1) relative to (ipos0).
 SeqPosition getIterator()
           
 SeqPosition getIterator(int index)
           
 SeqPosition getIteratorAtPos(int ipos)
           
 int getLowBound(int dim)
           
 int getNextKind(int ipos)
           
 java.lang.String getNextTypeName(int ipos)
           
 java.lang.Object getNextTypeObject(int ipos)
           
 java.lang.Object getPosNext(int ipos)
          Get the element following the specified position.
 java.lang.Object getPosPrevious(int ipos)
          Get the element before the specified position.
 int getSize(int dim)
           
protected  boolean gotoAttributesStart(TreePosition pos)
           
 boolean gotoChildrenStart(TreePosition pos)
          Set position before first child (of the element following position).
protected  boolean gotoParent(TreePosition pos)
           
 int hashCode()
           
 boolean hasNext(int ipos)
           
protected  boolean hasPrevious(int ipos)
          Called by SeqPosition.hasPrevious.
 int indexOf(java.lang.Object o)
          See java.util.List.
protected  boolean isAfterPos(int ipos)
          Tests whether the position has the "isAfter" property.
 boolean isEmpty()
           
 java.util.Iterator iterator()
           
 int lastIndexOf(java.lang.Object o)
          See java.util.List.
 java.util.ListIterator listIterator()
           
 java.util.ListIterator listIterator(int index)
           
protected  int nextIndex(int ipos)
          Get the offset from the beginning corresponding to a position cookie.
 int nextIndex(SeqPosition pos)
           
 int nextMatching(int startPos, ElementPredicate type, int endPos, boolean descend)
          Get next matching child or descendent (ignoring attributes).
 int nextPos(int ipos)
          Return the next position following the argument.
 int parentPos(int ipos)
          Get position of parent.
 int previousPos(int ipos)
          Return the previous position following the argument.
 int rank()
           
protected  void releasePos(int ipos)
          Reclaim any resources used by the given position int.
 java.lang.Object remove(int index)
           
 boolean remove(java.lang.Object o)
           
 boolean removeAll(java.util.Collection c)
           
 void removePos(int ipos, int count)
          Remove one or more elements.
protected  void removePosRange(int ipos0, int ipos1)
          Remove a range where each end-point is a position in a container.
 boolean retainAll(java.util.Collection c)
           
 java.lang.Object set(int[] indexes, java.lang.Object value)
           
 java.lang.Object set(int index, java.lang.Object element)
           
protected  void setPosNext(int ipos, java.lang.Object value)
           
protected  void setPosPrevious(int ipos, java.lang.Object value)
           
abstract  int size()
          See java.util.List.
 int stableCompare(AbstractSequence other)
          This is used for the XML concept of "document order".
 int startPos()
           
 java.util.List subList(int fromIx, int toIx)
           
 Sequence subSequence(SeqPosition start, SeqPosition end)
           
protected  Sequence subSequencePos(int ipos0, int ipos1)
           
 java.lang.Object[] toArray()
           
 java.lang.Object[] toArray(java.lang.Object[] arr)
           
 java.lang.String toString()
           
 void toString(java.lang.String sep, java.lang.StringBuffer sbuf)
           
protected  java.lang.RuntimeException unsupported(java.lang.String text)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AbstractSequence

public AbstractSequence()
Method Detail

size

public abstract int size()
See java.util.List.


isEmpty

public boolean isEmpty()

rank

public int rank()

get

public abstract java.lang.Object get(int index)
See java.util.List.


getEffectiveIndex

public int getEffectiveIndex(int[] indexes)

get

public java.lang.Object get(int[] indexes)

set

public java.lang.Object set(int[] indexes,
                            java.lang.Object value)

getLowBound

public int getLowBound(int dim)

getSize

public int getSize(int dim)

unsupported

protected java.lang.RuntimeException unsupported(java.lang.String text)

append

public AbstractSequence append(char c)

append

public AbstractSequence append(java.lang.CharSequence csq)
                        throws java.io.IOException
Throws:
java.io.IOException

append

public AbstractSequence append(java.lang.CharSequence csq,
                               int start,
                               int end)
                        throws java.io.IOException
Throws:
java.io.IOException

set

public java.lang.Object set(int index,
                            java.lang.Object element)

fill

public void fill(java.lang.Object value)

fillPosRange

public void fillPosRange(int fromPos,
                         int toPos,
                         java.lang.Object value)

fill

public void fill(int fromIndex,
                 int toIndex,
                 java.lang.Object value)

indexOf

public int indexOf(java.lang.Object o)
See java.util.List.


lastIndexOf

public int lastIndexOf(java.lang.Object o)
See java.util.List.


nextMatching

public int nextMatching(int startPos,
                        ElementPredicate type,
                        int endPos,
                        boolean descend)
Get next matching child or descendent (ignoring attributes).

Parameters:
startPos - starting position
type - a test (predicate) to apply to selected elements
endPos - stop before endPos
descend - if true do depth-first traversal.
Returns:
poistion of next match or 0 if none found

contains

public boolean contains(java.lang.Object o)
See java.util.List.


containsAll

public boolean containsAll(java.util.Collection c)
See java.util.List.


elements

public final java.util.Enumeration elements()

getIterator

public final SeqPosition getIterator()

getIterator

public SeqPosition getIterator(int index)

getIteratorAtPos

public SeqPosition getIteratorAtPos(int ipos)

iterator

public final java.util.Iterator iterator()

listIterator

public final java.util.ListIterator listIterator()

listIterator

public final java.util.ListIterator listIterator(int index)

addPos

protected int addPos(int ipos,
                     java.lang.Object value)
Add a value at a specified Pos.

Returns:
the updated Pos, which is after the inserted value..

add

public boolean add(java.lang.Object o)
See java.util.Collection.


add

public void add(int index,
                java.lang.Object o)
See java.util.List.


addAll

public boolean addAll(java.util.Collection c)
See java.util.Collection.


addAll

public boolean addAll(int index,
                      java.util.Collection c)
See java.util.Collection.


removePos

public void removePos(int ipos,
                      int count)
Remove one or more elements.

Parameters:
ipos - position where elements should be removed
count - if non-negative, remove that number of elements following (poses, posNumber); if negative the negative of the number of elements to remove before (poses, posNumber).
Throws:
java.lang.IndexOutOfBoundsException - if (count >= 0 ? (index < 0 || index + count > size()) : (index + count < 0 || index > size())), where index == nextIndex(ipos, xpos).

removePosRange

protected void removePosRange(int ipos0,
                              int ipos1)
Remove a range where each end-point is a position in a container.

Parameters:
ipos0 - start of range, as a poistion
ipos1 - end of range
Throws:
java.lang.IndexOutOfBoundsException - if nextIndex(ipos0) > nextIndex(ipos1) || nextIndex(ipos0) < 0 || nextIndex(ipos1) > size()

remove

public java.lang.Object remove(int index)

remove

public boolean remove(java.lang.Object o)

removeAll

public boolean removeAll(java.util.Collection c)

retainAll

public boolean retainAll(java.util.Collection c)

clear

public void clear()

isAfterPos

protected boolean isAfterPos(int ipos)
Tests whether the position has the "isAfter" property. I.e. if something is inserted at the position, will the iterator end up being after the new data?


createPos

public abstract int createPos(int index,
                              boolean isAfter)
Generate a position at a given index. The result is a position cookie that must be free'd with releasePos.

Parameters:
index - offset from beginning of desired position
isAfter - should the position have the isAfter property
Throws:
java.lang.IndexOutOfBoundsException - if index is out of bounds

createRelativePos

public int createRelativePos(int pos,
                             int delta,
                             boolean isAfter)

startPos

public int startPos()

endPos

public int endPos()

releasePos

protected void releasePos(int ipos)
Reclaim any resources used by the given position int.

Parameters:
ipos - the Pos being free'd.

copyPos

public int copyPos(int ipos)
Make a copy of a position int. For simple positions returns the argument. However, if the positions are magic cookies that are actively managed by the sequence (as opposed to for example a simple index), then making a copy may need to increment a reference count, or maybe allocate a new position cookie. In any case, the new position is initialized to the same offset (and isAfter property) as the original.

Parameters:
ipos - the position being copied.
Returns:
the new position

getIndexDifference

protected int getIndexDifference(int ipos1,
                                 int ipos0)
Get offset of (ipos1) relative to (ipos0).


nextIndex

protected int nextIndex(int ipos)
Get the offset from the beginning corresponding to a position cookie.


fromEndIndex

protected int fromEndIndex(int ipos)

getContainingSequenceSize

protected int getContainingSequenceSize(int ipos)
Get the size of the (sub-) sequence containing a given position. Normally the same as size(), but may be different if this Sequence is a tree and the position points at an interior node.


hasNext

public boolean hasNext(int ipos)

getNextKind

public int getNextKind(int ipos)

getNextTypeName

public java.lang.String getNextTypeName(int ipos)

getNextTypeObject

public java.lang.Object getNextTypeObject(int ipos)

hasPrevious

protected boolean hasPrevious(int ipos)
Called by SeqPosition.hasPrevious.


nextPos

public int nextPos(int ipos)
Return the next position following the argument. The new position has the isAfter property. The argument is implicitly released (as in releasePos). Returns 0 if we are already at end of file.


previousPos

public int previousPos(int ipos)
Return the previous position following the argument. The new position has the isBefore property. The argument is implicitly released (as in releasePos). Returns -1 if we are already at beginning of file.


gotoChildrenStart

public final boolean gotoChildrenStart(TreePosition pos)
Set position before first child (of the element following position).

Returns:
true if there is a child sequence (which might be empty); false if current position is end of sequence or following element is atomic (cannot have children).

firstChildPos

public int firstChildPos(int ipos)
Get position before first child (of the element following position).

Parameters:
ipos - parent position. It is not released by this method.
Returns:
non-zero position cookie if there is a child sequence (which might be empty); zero if current position is end of sequence or following element is atomic (cannot have children).

firstAttributePos

public int firstAttributePos(int ipos)
Like firstChildPos. Problem: Should this stop before we get to children? I think so, but that requires changes to TreeList.


parentPos

public int parentPos(int ipos)
Get position of parent.

Parameters:
ipos - child position. It is not released by this method.
Returns:
the p os of the parent, or endPos() is there is no known parent.

gotoParent

protected boolean gotoParent(TreePosition pos)

getAttributeLength

public int getAttributeLength()

getAttribute

public java.lang.Object getAttribute(int index)

gotoAttributesStart

protected boolean gotoAttributesStart(TreePosition pos)

getPosNext

public java.lang.Object getPosNext(int ipos)
Get the element following the specified position.

Parameters:
ipos - the specified position.
Returns:
the following element, or eofValue if there is none. Called by SeqPosition.getNext.

getPosPrevious

public java.lang.Object getPosPrevious(int ipos)
Get the element before the specified position.

Parameters:
ipos - the specified position.
Returns:
the following element, or eofValue if there is none.

setPosNext

protected void setPosNext(int ipos,
                          java.lang.Object value)

setPosPrevious

protected void setPosPrevious(int ipos,
                              java.lang.Object value)

nextIndex

public final int nextIndex(SeqPosition pos)

baseUriOfPos

public java.lang.Object baseUriOfPos(int pos)
Return of the base-uri property, if known, of the node at pos.


equals

public boolean equals(int ipos1,
                      int ipos2)
Compare two positions, and indicate if they are the same position.


compare

public int compare(int ipos1,
                   int ipos2)
Compare two positions, and indicate their relative order.


compare

public final int compare(SeqPosition i1,
                         SeqPosition i2)

toArray

public java.lang.Object[] toArray()

toArray

public java.lang.Object[] toArray(java.lang.Object[] arr)

stableCompare

public int stableCompare(AbstractSequence other)
This is used for the XML concept of "document order".


compare

public static int compare(AbstractSequence seq1,
                          int pos1,
                          AbstractSequence seq2,
                          int pos2)
This is used for the XML concept of "document order". It is overridden in gnu.xml.NodeTree for a more robust implementation.


hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

subSequence

public Sequence subSequence(SeqPosition start,
                            SeqPosition end)

subSequencePos

protected Sequence subSequencePos(int ipos0,
                                  int ipos1)

subList

public java.util.List subList(int fromIx,
                              int toIx)

consumeNext

public boolean consumeNext(int ipos,
                           Consumer out)
Copy an element specified by a position pair to a Consumer.

Returns:
if hasNext(ipos).

consumePosRange

public void consumePosRange(int iposStart,
                            int iposEnd,
                            Consumer out)

consume

public void consume(Consumer out)

toString

public void toString(java.lang.String sep,
                     java.lang.StringBuffer sbuf)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object