Saxon.Api

 

 

Saxon.Api

Class XdmValue

Direct Known Subclasses
XdmEmptySequence, XdmItem
public class XdmValue
implements IEnumerable<XdmItem>

A value in the XDM data model. A value is a sequence of zero or more items, each item being an atomic value, a node, or a function item.

An XdmValue is designed to be immutable.

An XdmValue is indexed, so you can get the n'th item in the value (starting from zero) by writing value[n]. Alternatively, use the method value.ItemAt(n).

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 all single-item sequences will be instances of XdmItem: if you want to ensure this, use the XdmValue.Simplify method.

There are various ways of creating an XdmValue. To create an atomic value, use one of the constructors on XdmAtomicValue (which is a subtype of XdmValue). To construct an XdmNode (another subtype) by parsing an XML document, or by wrapping a DOM document, use a DocumentBuilder. To create a sequence of values, use the XdmValue.Append(XdmValue) method on this class to form a list from individual items or sub-lists.

An XdmValue is also returned as the result of evaluating a query using the XQuery and XPath interfaces.

The subtype XdmEmptySequence represents an empty sequence: an XdmValue of length zero. Again, there is no guarantee that every empty sequence will be represented as an instance of XdmEmptySequence, unless you use the XdmValue.Simplify method.

Constructor Summary
XdmValue (IEnumerator<XdmItem> items)

Create an XdmValue from an enumerator of XdmItem objects.

XdmValue (IEnumerable<XdmItem> items)

Create a value from a collection of items.

 

Property Summary
 int Count

Get the number of items in the sequence.

 bool Empty

Ask whether the sequence is empty.

 

Indexer Summary
 XdmItem Item [int index]

Get a selected item in the sequence by position, counting from zero.

 

Method Summary
 <T> bool AllMatch (Predicate<T> predicate)

Ask whether all items of this XdmValue match the provided predicate. Might not evaluate the predicate on all items if not necessary for determining the result.

 <T> bool AnyMatch (Predicate<T> predicate)

Ask whether any item in this XdmValue matches the provided predicate. Might not evaluate the predicate on all items if not necessary for determining the result.

 XdmValue Append (XdmValue otherValue)

Create a new XdmValue by concatenating the sequences of items in this XdmValue and another XdmValue.

 XdmValue Atomize ()

Atomize a value (that is, replace nodes by their typed value)

static <TInput> IEnumerable<TInput> Concat (IEnumerable<TInput> first, IEnumerable<TInput> second)

Concatenate two IEnumerable objects of XdmItem objects or items of its subclass.

 XdmValue DocumentOrder ()

Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order.

 IEnumerator<XdmItem> GetEnumerator ()

Get the sequence of items in the form of an IEnumerator.

 IList<XdmItem> GetList ()

Get the sequence of items in the form of an IList.

 XdmValue GetRange (int index, int count)

Get a subsequence of the value.

 XdmItem ItemAt (int i)

Get the i'th item in the value, counting from zero.

static XdmValue MakeValue (object o)

Make an XDM value from a .NET object.

 bool Matches (XdmSequenceType type)

Ask whether this value is an instance of a supplied SequenceType

 <TInput, TResult> IEnumerable<TResult> Select (Step<TInput, TResult> step)

Get an IEnumerable by applying a Step to the items in this value. This operation is analogous to the SelectMany operation in C#, or to the "!" operator in XPath.

 XdmValue Simplify ()

Simplify an XDM value: that is, reduce it to the simplest possible form.

 string ToString ()

Create a string representation of the value. The is the result of serializing the value using the adaptive serialization method.

 net.sf.saxon.om.GroundedValue Unwrap ()

Extract the underlying Saxon Sequence object from an XdmValue. This method is provided for the benefit of applications that need to mix use of the Saxon .NET API with direct use of the underlying objects and methods offered by the Java implementation.

 <T> IEnumerable<T> Where (Predicate<T> predicate)

Get the collection of items that satisfy a supplied Predicate.

static XdmValue Wrap (net.sf.saxon.om.Sequence value)

Create an XdmValue from an underlying Saxon Sequence object.

 

Constructor Detail

XdmValue

public XdmValue(IEnumerator<XdmItem> items)

Create an XdmValue from an enumerator of XdmItem objects.

Parameters:

items - An enumerator of XdmItem objects

XdmValue

public XdmValue(IEnumerable<XdmItem> items)

Create a value from a collection of items.

Parameters:

items - An enumerable collection providing the items to make up the sequence. Every member of this collection must be an instance of XdmItem

Property Detail

Count

public int Count {get; }

Get the number of items in the sequence.

Returns:

The number of items in the sequence. Note that for a single item (including a map or an array) this always returns 1 (one).

Empty

public bool Empty {get; }

Ask whether the sequence is empty.

Returns:

True if the length of the sequence is zero. Note: there is no guarantee that an empty sequence will always be represented by an XdmEmptySequence object.

Indexer Detail

Item

public XdmItem this[int index]

Get a selected item in the sequence by position, counting from zero.

Retained for compatibility; but xdmValue.ItemAt(i) can also be written xdmValue[i]

Parameters:

index - The item that is required, counting the first item in the sequence as item zero.

Returns:

The item in the sequence at position index, counting from zero.

Method Detail

AllMatch

public bool AllMatch<T>(Predicate<T> predicate)

Ask whether all items of this XdmValue match the provided predicate. Might not evaluate the predicate on all items if not necessary for determining the result.

To test whether all items match a particular XDM item type, write for example .AllMatch(XdmAtomicType.Integer.Matches)

Parameters:

predicate - The predicate to apply to items of this XdmValue

Returns:

true if either all items of the XdmValue match the provided predicate or the XdmValue is empty, otherwise false

AnyMatch

public bool AnyMatch<T>(Predicate<T> predicate)

Ask whether any item in this XdmValue matches the provided predicate. Might not evaluate the predicate on all items if not necessary for determining the result.

To test whether any items match a particular XDM item type, write for example .AnyMatch(XdmAtomicType.Integer.Matches)

Parameters:

predicate - The predicate to apply to items of this XdmValue

Returns:

True if any items of the XdmValue match the provided predicate, otherwise false.

Append

public XdmValue Append(XdmValue otherValue)

Create a new XdmValue by concatenating the sequences of items in this XdmValue and another XdmValue.

Neither of the input XdmValue objects is modified by this operation.

Parameters:

otherValue -  The other XdmValue, whose items are to be appended to the items from this XdmValue.

Atomize

public XdmValue Atomize()

Atomize a value (that is, replace nodes by their typed value)

Returns:

The atomized value

Concat

public static IEnumerable<TInput> Concat<TInput>(IEnumerable<TInput> first,
IEnumerable<TInput> second)

Concatenate two IEnumerable objects of XdmItem objects or items of its subclass.

Parameters:

first - The first enumerable object
second - The second enumerable object

Returns:

The enumerable object as a result of the concatenation.

DocumentOrder

public XdmValue DocumentOrder()

Return a new XdmValue containing the nodes present in this XdmValue, with duplicates eliminated, and sorted into document order.

Returns:

The same nodes, sorted into document order, with duplicates eliminated.

GetEnumerator

public IEnumerator<XdmItem> GetEnumerator()

Get the sequence of items in the form of an IEnumerator.

Returns:

An enumeration over the list of items making up this XDM value. Each item in the list will be an object of type XdmItem.

GetList

public IList<XdmItem> GetList()

Get the sequence of items in the form of an IList.

Returns:

The list of items making up this XDM value. Each item in the list will be an object of type XdmItem.

GetRange

public XdmValue GetRange(int index,
int count)

Get a subsequence of the value.

Gets an XdmValue containing a contiguous subsequence of this value, starting at the given index and containing count items. Throws IndexOutOfRangeException if the index or count are out of range.

Parameters:

index - The index of the first item to be included.
count - The number of items to be included.

Returns:

The i'th item in the sequence making up the value, counting from zero.

ItemAt

public XdmItem ItemAt(int i)

Get the i'th item in the value, counting from zero.

Retained for compatibility; but xdmValue.ItemAt(i) can also be written xdmValue[i]

Parameters:

i - The item that is required, counting the first item in the sequence as item zero.

Returns:

The i'th item in the sequence making up the value, counting from zero.

MakeValue

public static XdmValue MakeValue(object o)

Make an XDM value from a .NET object.

The supplied object may be any of the following:

  • An instance of XdmValue (for example an XdmAtomicValue, XdmMap, XdmArray or XdmNode), which is returned unchanged
  • An instance of Saxon's Java class Saxon.Hej.om.Sequence, which is wrapped as an XdmValue
  • An instance of IDictionary (which is wrapped as an XdmMap using the method XdmMap.MakeMap(IDictionary))
  • An array of objects, which are converted by applying these rules recursively, and then wrapped as an XdmArray.

Parameters:

o - The supplied object

Returns:

The result of conversion if successful.

Matches

public bool Matches(XdmSequenceType type)

Ask whether this value is an instance of a supplied SequenceType

Parameters:

type - the type to be tested

Returns:

true if the this value conforms to the supplied SequenceType

Select

public IEnumerable<TResult> Select<TInput, TResult>(Step<TInput, TResult> step)

Get an IEnumerable by applying a Step to the items in this value. This operation is analogous to the SelectMany operation in C#, or to the "!" operator in XPath.

The following examples assume a using static declaration of the standard Steps: using static Saxon.Api.Steps;

  • Select(Child()) returns a stream containing all children
  • Select(Child("*")) returns a stream containing all element children
  • Select(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" descendants
  • Select(Path("//", "author", "@name")) returns a stream containing the "name" attributes of "author" descendants
  • Select(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 the first "author" child (if there is one)
  • Select(Child("author").Where(attributeEq("firstName", "Jane").Last()) returns the last "author" child having a "firstName" attribute whose value is "Jane" (if there is one)

In each of the above examples except the last two, the selected nodes are returned as an Enumerable<XdmNode>, so they can be processed using a foreach statement.

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.

Parameters:

step - The Step to be applied to the items in this value.

Returns:

An IEnumerable of items obtained by replacing each item X in this value by the items obtained by applying the Step function to X.

Simplify

public XdmValue Simplify()

Simplify an XDM value: that is, reduce it to the simplest possible form.

  • If the sequence is empty, the result will be an instance of XdmEmptySequence
  • If the sequence is a single node, the result will be an instance of XdmNode
  • If it is a single atomic value, it will be an instance of XdmAtomicValue
  • If it is a map, it will be an instance of XdmMap
  • If it is an array, it will be an instance of XdmArray
  • If it is any other kind of function, it will be an instance of XdmFunctionItem
  • If it is a wrapper around a .NET object, it will be an instance of XdmExternalObjectValue

Returns:

The XDM value reduced to the simplest possible form.

ToString

public override string ToString()

Create a string representation of the value. The is the result of serializing the value using the adaptive serialization method.

Returns:

A string representation of the value.

Unwrap

public net.sf.saxon.om.GroundedValue Unwrap()

Extract the underlying Saxon Sequence object from an XdmValue. This method is provided for the benefit of applications that need to mix use of the Saxon .NET API with direct use of the underlying objects and methods offered by the Java implementation.

Returns:

An object representing the XDM value in the underlying Saxon implementation.

Where

public IEnumerable<T> Where<T>(Predicate<T> predicate)

Get the collection of items that satisfy a supplied Predicate.

Parameters:

predicate - The predicate to be applied

Returns:

An enumerable of items that satisfy the supplied Predicate.

Wrap

public static XdmValue Wrap(net.sf.saxon.om.Sequence value)

Create an XdmValue from an underlying Saxon Sequence object.

Parameters:

value - An object representing an XDM value in the underlying Saxon implementation. If the parameter is null, the method returns null.

Returns:

An XdmValue that wraps the underlying Saxon XDM value representation.