net.sf.saxon.om

Class SequenceTool

java.lang.Object

net.sf.saxon.om.SequenceTool

public class SequenceTool
extends Object

Utility class for manipulating sequences. Some of these methods should be regarded as temporary scaffolding while the model is in transition.

Field Summary

Fields

Modifier and Type	Field and Description
static int	INDETERMINATE_ORDERING Constant returned by compareTo() method to indicate an indeterminate ordering between two values

Constructor Summary

Constructors

Constructor and Description
SequenceTool()

Method Summary

Methods

Modifier and Type	Method and Description
static Item	asItem(Sequence sequence) Static method to make an Item from a Value
static Object	convertToJava(Item item) Convert an XPath value to a Java object.
static int	getCardinality(Sequence sequence)
static ItemType	getItemType(Sequence sequence, TypeHierarchy th)
static int	getLength(Sequence sequence) Get the length of a sequence (the number of items it contains)
static String	getStringValue(Sequence sequence)
static Item	itemAt(Sequence sequence, int index) Get the item at a given offset in a sequence.
static void	process(Sequence value, XPathContext context, int locationId) Process the value as an instruction, without returning any tail calls
static GroundedValue	toGroundedValue(Sequence sequence) Produce a GroundedValue containing the same values as a supplied sequence.
static GroundedValue	toGroundedValue(SequenceIterator iterator) Produce a GroundedValue containing the same values as a supplied sequence.
static Sequence	toLazySequence(SequenceIterator iterator) Construct a sequence capable of returning the same items as an iterator, without incurring the cost of evaluating the iterator and storing all the items.
static Sequence	toMemoSequence(SequenceIterator iterator) Produce a Sequence containing the same values as a supplied sequence; the input is read progressively as required, and saved in a buffer as it is read in case it is needed again.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INDETERMINATE_ORDERING

public static final int INDETERMINATE_ORDERING

Constant returned by compareTo() method to indicate an indeterminate ordering between two values

See Also:

Constant Field Values

Constructor Detail

SequenceTool

public SequenceTool()

Method Detail

toGroundedValue

public static GroundedValue toGroundedValue(Sequence sequence)
                                     throws XPathException

Produce a GroundedValue containing the same values as a supplied sequence.

Parameters:

sequence - the supplied sequence

Returns:

a GroundedValue containing the same items

Throws:

XPathException

toGroundedValue

public static GroundedValue toGroundedValue(SequenceIterator iterator)
                                     throws XPathException

Produce a GroundedValue containing the same values as a supplied sequence.

Parameters:

iterator - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.

Returns:

a GroundedValue containing the same items

Throws:

XPathException - if a failure occurs reading the input iterator

toMemoSequence

public static Sequence toMemoSequence(SequenceIterator iterator)
                               throws XPathException

Produce a Sequence containing the same values as a supplied sequence; the input is read progressively as required, and saved in a buffer as it is read in case it is needed again. But if the iterator is already backed by a grounded value, we return an iterator over that value.

Parameters:

iterator - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.

Returns:

a GroundedValue containing the same items

Throws:

XPathException - if a failure occurs reading the input iterator

toLazySequence

public static Sequence toLazySequence(SequenceIterator iterator)
                               throws XPathException

Construct a sequence capable of returning the same items as an iterator, without incurring the cost of evaluating the iterator and storing all the items.

Parameters:

iterator - the supplied sequence. The iterator may or may not be consumed as a result of passing it to this method.

Returns:

a Sequence containing the same items as the supplied iterator

Throws:

XPathException - if a failure occurs reading the input iterator

getLength

public static int getLength(Sequence sequence)
                     throws XPathException

Get the length of a sequence (the number of items it contains)

Parameters:

sequence - the sequence

Returns:

the length in items

Throws:

XPathException

itemAt

public static Item itemAt(Sequence sequence,
          int index)
                   throws XPathException

Get the item at a given offset in a sequence. Uses zero-base indexing

Parameters:

sequence - the input sequence

index - the 0-based subscript

Returns:

the n'th item if it exists, or null otherwise

Throws:

XPathException

asItem

public static Item asItem(Sequence sequence)
                   throws XPathException

Static method to make an Item from a Value

Parameters:

sequence - the value to be converted

Returns:

null if the value is an empty sequence; or the only item in the value if it is a singleton sequence

Throws:

XPathException - if the supplied Sequence contains multiple items

convertToJava

public static Object convertToJava(Item item)
                            throws XPathException

Convert an XPath value to a Java object. An atomic value is returned as an instance of the best available Java class. If the item is a node, the node is "unwrapped", to return the underlying node in the original model (which might be, for example, a DOM or JDOM node).

Parameters:

item - the item to be converted

Returns:

the value after conversion

Throws:

XPathException - if an error occurs: for example, if the XPath value is an integer and is too big to fit in a Java long

getStringValue

public static String getStringValue(Sequence sequence)
                             throws XPathException

Throws:

XPathException

getItemType

public static ItemType getItemType(Sequence sequence,
                   TypeHierarchy th)

getCardinality

public static int getCardinality(Sequence sequence)

process

public static void process(Sequence value,
           XPathContext context,
           int locationId)
                    throws XPathException

Process the value as an instruction, without returning any tail calls

Parameters:

context - The dynamic context, giving access to the current node, the current variables, etc.

Throws:

XPathException - if an error occurs (for example if the value is a closure that needs to be evaluated)