public class XdmValue extends java.lang.Object implements java.lang.Iterable<XdmItem>
An XdmValue is immutable.
A sequence consisting of a single item may be represented as an instance of XdmItem
,
which is a subtype of XdmValue. However, there is no guarantee that a sequence of length one
will always be an instance of XdmItem.
Similarly, a zero-length sequence may be represented as an instance of XdmEmptySequence
,
but there is no guarantee that every sequence of length zero will always be an instance of
XdmEmptySequence.
Modifier | Constructor and Description |
---|---|
protected |
XdmValue(GroundedValue value)
Create an XdmValue that wraps a supplied
GroundedValue . |
|
XdmValue(java.lang.Iterable<? extends XdmItem> items)
Create an XdmValue as a sequence of XdmItem objects
|
|
XdmValue(java.util.Iterator<? extends XdmItem> iterator)
Create an XdmValue containing the items returned by an
Iterator . |
|
XdmValue(java.util.stream.Stream<? extends XdmItem> stream)
Create an XdmValue containing the results of reading a Stream
|
Modifier and Type | Method and Description |
---|---|
XdmValue |
append(XdmValue otherValue)
Create a new XdmValue by concatenating the contents of this XdmValue and another
XdmValue into a single sequence.
|
XdmValue |
documentOrder()
Return a new XdmValue containing the nodes present in this XdmValue,
with duplicates eliminated, and sorted into document order
|
GroundedValue |
getUnderlyingValue()
Get the underlying implementation object representing the value.
|
boolean |
isEmpty()
Ask whether the sequence is empty
|
XdmItem |
itemAt(int n)
Get the n'th item in the value, counting from zero.
|
XdmSequenceIterator<XdmItem> |
iterator()
Get an iterator over the items in this value.
|
static XdmValue |
makeSequence(java.lang.Iterable<?> list)
Make an XDM sequence from a Java
Iterable . |
static XdmValue |
makeValue(java.lang.Object o)
Make an XDM value from a Java object.
|
<T extends XdmItem> |
select(Step<T> step)
Get a stream of items by applying a
Step to the items in this value. |
int |
size()
Get the number of items in the sequence
|
XdmStream<? extends XdmItem> |
stream()
Get a stream comprising the items in this value
|
XdmValue |
subsequence(int start,
int length)
Get a subsequence of the value
|
java.lang.String |
toString()
Create a string representation of the value.
|
static XdmValue |
wrap(AtomicSequence value) |
static XdmValue |
wrap(Sequence value)
Create an XdmValue that wraps an existing Saxon Sequence
|
protected XdmValue(GroundedValue value)
GroundedValue
. This
method is primarily for internal use, though it is also available to applications
that manipulate data using lower-level Saxon interfaces.
Note that this constructor necessarily produces an XdmValue
regardless
of the supplied value. To construct instances of subclasses of XdmValue
,
such as XdmAtomicValue
or XdmNode
, use the wrap(net.sf.saxon.om.Sequence)
method,
or use the overriding constructor on the required subclass.
value
- the value to be wrapped.public XdmValue(java.lang.Iterable<? extends XdmItem> items)
items
- a sequence of XdmItem objects. Note that if this is supplied as a list or similar
collection, subsequent changes to the list/collection will have no effect on the XdmValue.public XdmValue(java.util.Iterator<? extends XdmItem> iterator) throws SaxonApiException
Iterator
.iterator
- the iterator that supplies the valuesSaxonApiException
- if an error occurs reading values from the supplied iteratorXdmSequenceIterator
.public XdmValue(java.util.stream.Stream<? extends XdmItem> stream) throws SaxonApiException
stream
- the stream to be readSaxonApiException
- if an error occurs reading values from the supplied streampublic static XdmValue wrap(Sequence value)
value
- the supplied Sequence (which may be a singleton Item),SaxonApiUncheckedException
- if the supplied Sequence is not yet fully evaluated, and evaluation
of the underlying expression fails with a dynamic error.public static XdmValue wrap(AtomicSequence value)
public XdmValue append(XdmValue otherValue)
Note: creating a sequence of N values by successive calls on this method takes time proportional to N-squared.
otherValue
- the value to be appendedpublic int size()
public boolean isEmpty()
public XdmItem itemAt(int n) throws java.lang.IndexOutOfBoundsException, SaxonApiUncheckedException
n
- the item that is required, counting the first item in the sequence as item zerojava.lang.IndexOutOfBoundsException
- if n is less than zero or greater than or equal to the number
of items in the valueSaxonApiUncheckedException
- if the value is lazily evaluated and the delayed
evaluation fails with a dynamic error.public XdmValue subsequence(int start, int length)
start
- the index of the first item to be included in the result, counting from zero.
A negative value is taken as zero. If the value is beyond the end of the sequence, an empty
sequence is returnedlength
- the number of items to be included in the result. Specify Integer.MAX_VALUE to
get the subsequence up to the end of the base sequence. If the value is negative, an empty sequence
is returned. If the length goes off the end of the sequence, the result returns items up to the end
of the sequencepublic XdmSequenceIterator<XdmItem> iterator() throws SaxonApiUncheckedException
iterator
in interface java.lang.Iterable<XdmItem>
SaxonApiUncheckedException
- if the value is lazily evaluated and the delayed
evaluation fails with a dynamic error.public GroundedValue getUnderlyingValue()
public java.lang.String toString()
toString
in class java.lang.Object
public static XdmValue makeSequence(java.lang.Iterable<?> list) throws java.lang.IllegalArgumentException
Iterable
. Each value delivered by the iterable
is first converted to an XDM value using the makeValue(Object)
method;
if the result is anything other than a single XDM item, it is then wrapped in an
XdmArray
.list
- the Java iterablejava.lang.IllegalArgumentException
- if conversion is not possiblepublic static XdmValue makeValue(java.lang.Object o) throws java.lang.IllegalArgumentException
XdmValue
(for example, an
XdmNode
or XdmAtomicValue
or XdmArray
or XdmMap
),
which is returned unchangedSequence
(for example, a
NodeInfo
or AtomicValue
),
which is wrapped as an XdmValue
Map
, which is converted to an XDM Map using
the XdmMap.makeMap(java.util.Map<K, V>)
methodXdmArray.makeArray(java.lang.Object[])
methodIterable
, which is converted to an XDM sequence
using the makeSequence(Iterable)
methodXdmAtomicValue.makeAtomicValue(Object)
o
- the Java objectjava.lang.IllegalArgumentException
- if conversion is not possiblepublic XdmValue documentOrder() throws SaxonApiException
SaxonApiException
- if anything goes wrong (typically during delayed evaluation of the
input sequence)java.lang.ClassCastException
- if the sequence contains items that are not nodespublic XdmStream<? extends XdmItem> stream()
public <T extends XdmItem> XdmStream<T> select(Step<T> step)
Step
to the items in this value. This operation
is analogous to the Stream.flatMap
operation in Java, or to the "!" operator
in XPath.
The following examples assume a static import declaration of the standard Steps:
import static net.sf.saxon.s9api.streams.Steps.*;
select(child())
returns a stream containing all childrenselect(child("*"))
returns a stream containing all element childrenselect(child("author"))
returns a stream containing all element children with
local name "author" (regardless of namespace)select(child("http://my.ns/", "author"))
returns a stream containing all element children with
local name "author" and namespace "http://my.ns/"select(descendant("author"))
returns a stream containing all element descendants with
local name "author" (regardless of namespace)select(descendant("author").then(attribute("name"))
returns a stream containing the "name"
attributes of "author" descendantsselect(path("//", "author", "@name"))
returns a stream containing the "name"
attributes of "author" descendantsselect(child("author").where(attributeEq("firstName", "Jane"))
returns a stream
containing all the "author" children having a "firstName" attribute whose value is "Jane"select(child("author").first())
returns a stream containing the first "author" child
(if there is one)select(child("author").where(attributeEq("firstName", "Jane").last())
returns a stream
containing the last "author" child having a "firstName" attribute whose value is "Jane" (if there is one)In each of the above examples, the selected nodes are returned as an XdmStream
<XdmNode
>; this
class extends Stream
<XdmNode
>, so all the standard operations on streams are
available, together with some additional operations specific to node streams.
The select
method thus has comparable power to simple XPath expressions; but unlike
XPath expressions, there is no run-time overhead in parsing the XPath expression and developing an
execution plan.
T
- the type of items to be returned by the step (often XdmNode
)step
- the Step
to be applied to the items in this value. This will often be one of the standard
steps returned by the static methods of the Steps
class, such as Steps.child()
,
or by instance methods (such as Step.where(java.util.function.Predicate<? super T>)
, Step.cat(net.sf.saxon.s9api.streams.Step<T>)
, or Step.first()
)
but it is also possible to create user-defined steps.Copyright (c) 2004-2022 Saxonica Limited. All rights reserved.