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 <T extends Item<?>> T	asItem(Sequence<T> 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 Sequence<?>[]	fromItems(Item<?>... items) Make an array of general-purpose Sequence objects with supplied contents
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) Get a sequence type to which a given value conforms
static <T extends Item<?>> java.lang.String	getStringValue(Sequence<T> 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 <T extends Item<?>> T	itemAt(Sequence<T> sequence, int index) Get the item at a given offset in a sequence.
static Sequence<?>[]	makeSequenceArray(int length) Make an array of general-purpose Sequence objects of a given length
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 <T extends Item<?>> GroundedValue<T>	toGroundedValue(SequenceIterator<T> iterator) Produce a GroundedValue containing the same values as a supplied sequence.
static <T extends Item<?>> Sequence<T>	toLazySequence(SequenceIterator<T> 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<?>	toLazySequence2(SequenceIterator<?> iterator)
static <T extends Item<?>> Sequence<T>	toMemoSequence(SequenceIterator<T> 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 <T extends Item<?>> GroundedValue<T> toGroundedValue(SequenceIterator<T> 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 <T extends Item<?>> Sequence<T> toMemoSequence(SequenceIterator<T> 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 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 Sequence containing the same items

Throws:

XPathException - if a failure occurs reading the input iterator

toLazySequence

public static <T extends Item<?>> Sequence<T> toLazySequence(SequenceIterator<T> 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

toLazySequence2

public static Sequence<?> toLazySequence2(SequenceIterator<?> iterator)
                                   throws XPathException

Throws:

XPathException

isUnrepeatable

public static boolean isUnrepeatable(Sequence<?> seq)

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 <T extends Item<?>> T itemAt(Sequence<T> 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 <T extends Item<?>> T asItem(Sequence<T> 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 <T extends Item<?>> java.lang.String getStringValue(Sequence<T> 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

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)

getSequenceType

public static SequenceType getSequenceType(Sequence<?> value,
                                           TypeHierarchy th)

Get a sequence type to which a given value conforms

Parameters:

value - the given value

th - the type hierarchy cache

Returns:

the best available sequence type to which the supplied value conforms

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)

makeSequenceArray

public static Sequence<?>[] makeSequenceArray(int length)

Make an array of general-purpose Sequence objects of a given length

Parameters:

length - the length of the returned array

fromItems

public static Sequence<?>[] fromItems(Item<?>... items)

Make an array of general-purpose Sequence objects with supplied contents