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 AttributeMap	attributeMapFromList(java.util.List<AttributeInfo> list) Construct an AttributeMap given a list of AttributeInfo objects representing the individual attributes.
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 int	getLength(SequenceIterator iterator) Get the number of items in the sequence identified by a SequenceIterator.
static UnicodeString	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 GroundedValue	itemOrEmpty(Item item) Helper method to convert an Item or null to a Sequence
static Sequence[]	makeSequenceArray(int length) Make an array of general-purpose Sequence objects of a given length
static void	process(Sequence value, Outputter output, 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 java.lang.String	stringify(Sequence sequence) Get the string value of a sequence.
static void	supply(SequenceIterator iter, ItemConsumer<? super Item> consumer) Supply the (remaining) items in a sequence to a consumer of items
static boolean	supportsGetLength(SequenceIterator iterator) Ask whether a SequenceIterator supports the capability to call getLength() to establish the number of items in the 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(SequenceIterator iterator)

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:

UncheckedXPathException - 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 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 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

supportsGetLength

public static boolean supportsGetLength(SequenceIterator iterator)

Ask whether a SequenceIterator supports the capability to call getLength() to establish the number of items in the sequence.

Parameters:

iterator - the iterator we are asking about

Returns:

true if the iterator is a LastPositionFinder with this capability. Note that some iterators implement this interface, but do not actually have the capability to determine the length, because they delegate to another iterator.

getLength

public static int getLength(SequenceIterator iterator)

Get the number of items in the sequence identified by a SequenceIterator. This method can only be used if supportsGetLength(SequenceIterator) has been called and returns true. The length is returned regardless of the current position of the iterator. The state of the iterator is not changed

Parameters:

iterator - the iterator we are asking about

Returns:

the number of items in the sequence

Throws:

java.lang.UnsupportedOperationException - if the iterator does not have this capability

supply

public static void supply(SequenceIterator iter,
                          ItemConsumer<? super Item> consumer)

Supply the (remaining) items in a sequence to a consumer of items

Parameters:

iter - a sequence iterator, which will be consumed by calling this method

consumer - the consumer which will be called to process the remaining items in the sequence, in turn

Throws:

UncheckedXPathException - if the computation of the input sequence reports an XPathException, or if the consymer throws an 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

Note: this is more efficient than counting the items and testing whether the result is N, because the sequence only needs to be read as far as the Nth item.

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 - if an error is detected

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 sequence

Returns:

true if the lengths of the two sequences are the same

Throws:

XPathException - if an error is detected

itemAt

public static Item itemAt(Sequence sequence,
                          int index)

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:

UncheckedXPathException - 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 UnicodeString 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

stringify

public static java.lang.String stringify(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

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,
                           Outputter output,
                           Location locationId)
                    throws XPathException

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

Parameters:

value - the sequence to be processed

output - the destination for the result

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

Returns:

the new array

fromItems

public static Sequence[] fromItems(Item... items)

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

Parameters:

items - the contents for the array

Returns:

the new array

attributeMapFromList

public static AttributeMap attributeMapFromList(java.util.List<AttributeInfo> list)

Construct an AttributeMap given a list of AttributeInfo objects representing the individual attributes.

Parameters:

list - the list of attributes. It is the caller's responsibility to ensure that this list contains no duplicates. The method may detect this, but is not guaranteed to do so. Calling AttributeMap.verify() after constructing the attribute map verifies that there are no duplicates. The order of items in the input list is not necessarily preserved.

Returns:

an AttributeMap containing the specified attributes.

Throws:

java.lang.IllegalArgumentException - if duplicate attributes are detected

itemOrEmpty

public static GroundedValue itemOrEmpty(Item item)

Helper method to convert an Item or null to a Sequence

Parameters:

item - the item to convert

Returns:

the converted sequence