Package net.sf.saxon.om
Class SequenceTool
java.lang.Object
net.sf.saxon.om.SequenceTool
Utility class for manipulating sequences. Some of these methods should be regarded
as temporary scaffolding while the model is in transition.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Constant returned by compareTo() method to indicate an indeterminate ordering between two values -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic Item
Static method to make an Item from a Valuestatic Object
convertToJava
(Item item) Convert an XPath value to a Java object.static Sequence[]
Make an array of general-purpose Sequence objects with supplied contentsstatic int
getCardinality
(Sequence sequence) Get the cardinality of a sequencestatic ItemType
getItemType
(Sequence sequence, TypeHierarchy th) Get the item type of the items in a sequence.static int
Get the length of a sequence (the number of items it contains)static String
getStringValue
(Sequence sequence) Get the string value of a sequence.static UType
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 Nstatic boolean
isUnrepeatable
(Sequence seq) static Item
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 lengthstatic void
Process a supplied value by copying it to the current output destinationstatic boolean
Determine whether two sequences have the same number of items.static <T extends Item>
GroundedValuetoGroundedValue
(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
toLazySequence2
(SequenceIterator iterator) 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.
-
Field Details
-
INDETERMINATE_ORDERING
public static final int INDETERMINATE_ORDERINGConstant returned by compareTo() method to indicate an indeterminate ordering between two values- See Also:
-
-
Constructor Details
-
SequenceTool
public SequenceTool()
-
-
Method Details
-
toGroundedValue
public static <T extends Item> 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
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
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
- Throws:
XPathException
-
isUnrepeatable
-
getLength
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
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
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 sequenceb
- iterator over the second sequece- Returns:
- true if the lengths of the two sequences are the same
- Throws:
XPathException
-
itemAt
Get the item at a given offset in a sequence. Uses zero-base indexing- Parameters:
sequence
- the input sequenceindex
- 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
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
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
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
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 sequenceth
- the Type Hierarchy cache- Returns:
- the lowest common supertype of the types of the items in the sequence
-
getUType
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
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), orStaticProperty.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 processedoutput
- the destination for the resultlocationId
- (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
Make an array of general-purpose Sequence objects of a given length- Parameters:
length
- the length of the returned array
-
fromItems
Make an array of general-purpose Sequence objects with supplied contents
-