gnu.lists

Class AbstractSequence

Known Direct 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.

Method Summary

boolean
add(Object o)
See java.util.Collection.
void
add(int index, Object o)
See java.util.List.
boolean
addAll(Collection c)
See java.util.Collection.
boolean
addAll(int index, Collection c)
See java.util.Collection.
protected int
addPos(int ipos, Object value)
Add a value at a specified Pos.
AbstractSequence
append(char c)
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(SeqPosition i1, SeqPosition i2)
int
compare(int ipos1, int ipos2)
Compare two positions, and indicate their relative order.
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(Object o)
See java.util.List.
boolean
containsAll(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)
Enumeration
elements()
int
endPos()
boolean
equals(Object o)
boolean
equals(int ipos1, int ipos2)
Compare two positions, and indicate if they are the same position.
void
fill(Object value)
void
fill(int fromIndex, int toIndex, Object value)
void
fillPosRange(int fromPos, int toPos, 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 Object
get(int index)
See java.util.List.
Object
get(int[] indexes)
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)
String
getNextTypeName(int ipos)
Object
getNextTypeObject(int ipos)
Object
getPosNext(int ipos)
Get the element following the specified position.
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)
boolean
hasNext(int ipos)
protected boolean
hasPrevious(int ipos)
Called by SeqPosition.hasPrevious.
int
hashCode()
int
indexOf(Object o)
See java.util.List.
protected boolean
isAfterPos(int ipos)
Tests whether the position has the "isAfter" property.
boolean
isEmpty()
Iterator
iterator()
int
lastIndexOf(Object o)
See java.util.List.
ListIterator
listIterator()
ListIterator
listIterator(int index)
int
nextIndex(SeqPosition pos)
protected int
nextIndex(int ipos)
Get the offset from the beginning corresponding to a position cookie.
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.
boolean
remove(Object o)
Object
remove(int index)
boolean
removeAll(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(Collection c)
Object
set(int index, Object element)
Object
set(int[] indexes, Object value)
protected void
setPosNext(int ipos, Object value)
protected void
setPosPrevious(int ipos, 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()
List
subList(int fromIx, int toIx)
Sequence
subSequence(SeqPosition start, SeqPosition end)
protected Sequence
subSequencePos(int ipos0, int ipos1)
Object[]
toArray()
Object[]
toArray(Object[] arr)
String
toString()
void
toString(String sep, StringBuffer sbuf)
protected RuntimeException
unsupported(String text)

Method Details

add

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

add

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

addAll

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

addAll

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

addPos

protected int addPos(int ipos,
                     Object value)
Add a value at a specified Pos.
Returns:
the updated Pos, which is after the inserted value..

append

public AbstractSequence append(char c)

baseUriOfPos

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

clear

public void clear()

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.

compare

public final int compare(SeqPosition i1,
                         SeqPosition i2)

compare

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

consume

public void consume(Consumer out)

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)

contains

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

containsAll

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

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

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

createRelativePos

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

elements

public final Enumeration elements()

endPos

public int endPos()

equals

public boolean equals(Object o)

equals

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

fill

public void fill(Object value)

fill

public void fill(int fromIndex,
                 int toIndex,
                 Object value)

fillPosRange

public void fillPosRange(int fromPos,
                         int toPos,
                         Object value)

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.

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

fromEndIndex

protected int fromEndIndex(int ipos)

get

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

get

public Object get(int[] indexes)

getAttribute

public Object getAttribute(int index)

getAttributeLength

public int getAttributeLength()

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.

getEffectiveIndex

public int getEffectiveIndex(int[] indexes)

getIndexDifference

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

getIterator

public final SeqPosition getIterator()

getIterator

public SeqPosition getIterator(int index)

getIteratorAtPos

public SeqPosition getIteratorAtPos(int ipos)

getLowBound

public int getLowBound(int dim)

getNextKind

public int getNextKind(int ipos)

getNextTypeName

public String getNextTypeName(int ipos)

getNextTypeObject

public Object getNextTypeObject(int ipos)

getPosNext

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

getSize

public int getSize(int dim)

gotoAttributesStart

protected boolean gotoAttributesStart(TreePosition pos)

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

gotoParent

protected boolean gotoParent(TreePosition pos)

hasNext

public boolean hasNext(int ipos)

hasPrevious

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

hashCode

public int hashCode()

indexOf

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

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?

isEmpty

public boolean isEmpty()

iterator

public final Iterator iterator()

lastIndexOf

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

listIterator

public final ListIterator listIterator()

listIterator

public final ListIterator listIterator(int index)

nextIndex

public final int nextIndex(SeqPosition pos)

nextIndex

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

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

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.

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.

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.

rank

public int rank()

releasePos

protected void releasePos(int ipos)
Reclaim any resources used by the given position int.
Parameters:
ipos - the Pos being free'd.

remove

public boolean remove(Object o)

remove

public Object remove(int index)

removeAll

public boolean removeAll(Collection c)

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

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

retainAll

public boolean retainAll(Collection c)

set

public Object set(int index,
                  Object element)

set

public Object set(int[] indexes,
                  Object value)

setPosNext

protected void setPosNext(int ipos,
                          Object value)

setPosPrevious

protected void setPosPrevious(int ipos,
                              Object value)

size

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

stableCompare

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

startPos

public int startPos()

subList

public List subList(int fromIx,
                    int toIx)

subSequence

public Sequence subSequence(SeqPosition start,
                            SeqPosition end)

subSequencePos

protected Sequence subSequencePos(int ipos0,
                                  int ipos1)

toArray

public Object[] toArray()

toArray

public Object[] toArray(Object[] arr)

toString

public String toString()

toString

public void toString(String sep,
                     StringBuffer sbuf)

unsupported

protected RuntimeException unsupported(String text)