net.sf.saxon.om

Class SequenceTool

java.lang.Object

net.sf.saxon.om.SequenceTool

public class SequenceTool
extends java.lang.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

Modifier and Type	Method and Description
static Item	asItem(Sequence sequence) Static method to make an Item from a Value
static java.lang.Object	convertToJava(Item item) Convert an XPath value to a Java object.
static int	getCardinality(Sequence sequence) Get the cardinality of a sequence
static ItemType	getItemType(Sequence sequence, TypeHierarchy th) Get the item type of the items in a sequence.
static int	getLength(Sequence sequence) Get the length of a sequence (the number of items it contains)
static SequenceType	getSequenceType(Sequence value, TypeHierarchy th)
static java.lang.String	getStringValue(Sequence sequence) Get the string value of a sequence.
static UType	getUType(Sequence sequence) Get the UType of the items in a sequence.
static boolean	hasLength(SequenceIterator iter, int length) Ask whether the length of a sequence is exactly N
static boolean	isUnrepeatable(Sequence seq)
static Item	itemAt(Sequence sequence, int index) Get the item at a given offset in a sequence.
static Sequence	makeRepeatable(Sequence seq)
static void	process(Sequence value, XPathContext context, Location locationId) Process a supplied value by copying it to the current output destination
static boolean	sameLength(SequenceIterator a, SequenceIterator b) Determine whether two sequences have the same number of items.
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 - for example if the value is a closure that needs to be evaluated, and evaluation fails

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

isUnrepeatable

public static boolean isUnrepeatable(Sequence seq)

makeRepeatable

public static Sequence makeRepeatable(Sequence seq)
                               throws XPathException

Throws:

XPathException

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 - if an error occurs (due to lazy evaluation)

hasLength

public static boolean hasLength(SequenceIterator iter,
                                int length)
                         throws XPathException

Ask whether the length of a sequence is exactly N

Parameters:

iter - an iterator over the sequence in question (which is typically consumed)

length - the supposed length

Returns:

true if and only if the length of the sequence is the supposed length

Throws:

XPathException

sameLength

public static boolean sameLength(SequenceIterator a,
                                 SequenceIterator b)
                          throws XPathException

Determine whether two sequences have the same number of items. This is more efficient than comparing the counts, because the longer sequence is evaluated only as far as the length of the shorter sequence. The method consumes the supplied iterators.

Parameters:

a - iterator over the first sequence

b - iterator over the second sequece

Returns:

true if the lengths of the two sequences are the same

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 - for example if the value is a closure that needs to be evaluated, and evaluation fails

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 java.lang.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 java.lang.String getStringValue(Sequence sequence)
                                       throws XPathException

Get the string value of a sequence. For an item, this is same as the result of calling the XPath string() function. For a sequence of more than one item, it is the concatenation of the individual string values of the items in the sequence, space-separated.

Parameters:

sequence - the input sequence

Returns:

a string representation of the items in the supplied sequence

Throws:

XPathException - if the sequence contains an item with no string value, for example a function item

getItemType

public static ItemType getItemType(Sequence sequence,
                                   TypeHierarchy th)

Get the item type of the items in a sequence. If the sequence is heterogeneous, the method returns the lowest common supertype. If the sequence is empty, it returns ErrorType (the type to which no instance can belong)

Parameters:

sequence - the input sequence

th - the Type Hierarchy cache

Returns:

the lowest common supertype of the types of the items in the sequence

getSequenceType

public static SequenceType getSequenceType(Sequence value,
                                           TypeHierarchy th)

getUType

public static UType getUType(Sequence sequence)

Get the UType of the items in a sequence. If the sequence is heterogeneous, the method returns the lowest common supertype. If the sequence is empty, it returns ErrorType (the type to which no instance can belong)

Parameters:

sequence - the input sequence

Returns:

the lowest common supertype of the types of the items in the sequence

getCardinality

public static int getCardinality(Sequence sequence)

Get the cardinality of a sequence

Parameters:

sequence - the supplied sequence

Returns:

the cardinality, as one of the constants StaticProperty.ALLOWS_ZERO (for an empty sequence) StaticProperty.EXACTLY_ONE (for a singleton), or StaticProperty.ALLOWS_ONE_OR_MORE (for a sequence with more than one item)

process

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

Process a supplied value by copying it to the current output destination

Parameters:

value - the sequence to be processed

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

locationId - (can be set to -1 if absent) information about the location of the value, which can be resolved by reference to the PipelineConfiguration of the current output destination

Throws:

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