net.sf.saxon.om

Interface Item

All Superinterfaces:

GroundedValue, Sequence

All Known Subinterfaces:

ArrayItem, ExternalObject<T>, Function, MapItem, MutableNodeInfo, NodeInfo, SiblingCountingNode, SteppingNode<N>, VirtualNode

All Known Implementing Classes:

Abs, AbsentExtensionElement, AbstractArrayItem, AbstractFunction, AbstractNodeWrapper, AbstractVirtualNode, AccessorFn, AccessorFn.DayFromDate, AccessorFn.DayFromDateTime, AccessorFn.DaysFromDuration, AccessorFn.HoursFromDateTime, AccessorFn.HoursFromDuration, AccessorFn.HoursFromTime, AccessorFn.LocalNameFromQName, AccessorFn.MinutesFromDateTime, AccessorFn.MinutesFromDuration, AccessorFn.MinutesFromTime, AccessorFn.MonthFromDate, AccessorFn.MonthFromDateTime, AccessorFn.MonthsFromDuration, AccessorFn.NamespaceUriFromQName, AccessorFn.PrefixFromQName, AccessorFn.SecondsFromDateTime, AccessorFn.SecondsFromDuration, AccessorFn.SecondsFromTime, AccessorFn.TimezoneFromDate, AccessorFn.TimezoneFromDateTime, AccessorFn.TimezoneFromTime, AccessorFn.YearFromDate, AccessorFn.YearFromDateTime, AccessorFn.YearsFromDuration, AccumulatorFn, AccumulatorFn.AccumulatorAfter, AccumulatorFn.AccumulatorBefore, Adjust_1, Adjust_2, Aggregate, AnalyzeStringFn, AnyURIValue, ApplyFn, ArrayFunctionSet.ArrayAppend, ArrayFunctionSet.ArrayFilter, ArrayFunctionSet.ArrayFlatten, ArrayFunctionSet.ArrayFoldLeft, ArrayFunctionSet.ArrayFoldRight, ArrayFunctionSet.ArrayForEach, ArrayFunctionSet.ArrayForEachPair, ArrayFunctionSet.ArrayFromSequence, ArrayFunctionSet.ArrayGet, ArrayFunctionSet.ArrayHead, ArrayFunctionSet.ArrayInsertBefore, ArrayFunctionSet.ArrayJoin, ArrayFunctionSet.ArrayPut, ArrayFunctionSet.ArrayRemove, ArrayFunctionSet.ArrayReverse, ArrayFunctionSet.ArraySize, ArrayFunctionSet.ArraySubarray, ArrayFunctionSet.ArrayTail, ArrayFunctionSet.ArrayToSequence, ArraySort, AtomicConstructorFunction, AtomicValue, AttributeImpl, AvailableEnvironmentVariables, AvailableSystemProperties, Average, AxiomAttributeWrapper, AxiomDocumentNodeWrapper, AxiomElementNodeWrapper, AxiomLeafNodeWrapper, AxiomParentNodeWrapper, Base64BinaryValue, BaseUri_1, BigDecimalValue, BigIntegerValue, Bindery.FailureValue, BooleanFn, BooleanValue, CalendarValue, CallableFunction, Ceiling, CodepointEqual, CodepointsToString, CoercedFunction, CollatingFunctionFixed, CollatingFunctionFree, CollationKeyFn, CollectionFn, CommentImpl, Compare, Concat, ConstantFunction, ConstantFunction.False, ConstantFunction.True, Contains, ContainsToken, ContextAccessorFunction, ContextItemAccessorFunction, ContextItemAccessorFunction.Number_0, ContextItemAccessorFunction.StringAccessor, CopyOfFn, Count, Current, CurrentGroup, CurrentGroupingKey, CurrentMergeGroup, CurrentMergeKey, CurrentOutputUri, CurriedFunction, Data_1, DataElement, DateTimeConstructor, DateTimeValue, DateValue, DayTimeDurationValue, DecimalValue, DeepEqual, DictionaryMap, DistinctValues, Doc, Doc_2, DocAvailable, DocumentFn, DocumentImpl, DocumentUri_1, DOM4JNodeWrapper, DOMNodeWrapper, DoubleValue, DurationValue, DynamicContextAccessor, DynamicContextAccessor.CurrentDate, DynamicContextAccessor.CurrentDateTime, DynamicContextAccessor.CurrentTime, DynamicContextAccessor.DefaultLanguage, DynamicContextAccessor.ImplicitTimezone, ElementAvailable, ElementImpl, Empty, EncodeForUri, EndsWith, EnvironmentVariable, Error, EscapeHtmlUri, Exists, ExsltCommonFunctionSet.NodeSetFn, ExsltCommonFunctionSet.ObjectTypeFn, ExtensionInstruction, FilterFn, FloatValue, Floor, FoldingFunction, FoldLeftFn, FoldRightFn, ForEachFn, ForEachPairFn, FormatDate, FormatInteger, FormatNumber, FunctionArity, FunctionAvailable, FunctionLookup, FunctionName, GDateValue, GDayValue, GenerateId_1, GMonthDayValue, GMonthValue, GYearMonthValue, GYearValue, HasChildren_1, HashTrieMap, HeadFn, HexBinaryValue, Idref, ImmutableArrayItem, IndexOf, Innermost, InScopePrefixes, InsertBefore, Int64Value, IntegerValue, IriToUri, JDOM2NodeWrapper, JsonDoc, JsonToXMLFn, KeyFn, Lang, ListCastableFunction, ListConstructorFunction, LiteralResultElement, LoadXqueryModule, LocalName_1, LowerCase, MapCreate, MapFunctionSet.MapContains, MapFunctionSet.MapEntry, MapFunctionSet.MapFind, MapFunctionSet.MapForEach, MapFunctionSet.MapGet, MapFunctionSet.MapKeys, MapFunctionSet.MapMerge, MapFunctionSet.MapPut, MapFunctionSet.MapRemove, MapFunctionSet.MapSize, MapUntypedContains, Matches, MathFunctionSet.AcosFn, MathFunctionSet.AsinFn, MathFunctionSet.Atan2Fn, MathFunctionSet.AtanFn, MathFunctionSet.CosFn, MathFunctionSet.Exp10Fn, MathFunctionSet.ExpFn, MathFunctionSet.Log10Fn, MathFunctionSet.LogFn, MathFunctionSet.PiFn, MathFunctionSet.PowFn, MathFunctionSet.SinFn, MathFunctionSet.SqrtFn, MathFunctionSet.TanFn, MemoFunction, Minimax, Minimax.Max, Minimax.Min, Name_1, NamespaceForPrefix, NamespaceNode, NamespaceUri_1, NestedIntegerValue, Nilled_1, NodeImpl, NodeName_1, NormalizeSpace_1, NormalizeUnicode, NotationValue, NotFn, Number_1, NumericValue, ObjectValue, OriginalFunction, Orphan, Outermost, ParentNodeImpl, ParseIetfDate, ParseJsonFn, ParseXml, ParseXmlFragment, Path_1, PositionAndLast, PositionAndLast.Last, PositionAndLast.Position, ProcInstImpl, Put, QNameFn, QNameValue, QualifiedNameValue, RandomNumberGenerator, RangeKey, RebasedNode, RegexFunction, RegexFunctionSansFlags, RegexGroup, Remove, Replace, ResolveQName, ResolveURI, Reverse, Root_1, Round, RoundHalfToEven, ScalarSystemFunction, Serialize, SimpleArrayItem, SingleEntryMap, SnapshotFn, SnapshotNode, Sort_1, Sort_2, Sort_3, SpaceStrippedNode, SQLClose, SQLColumn, SQLConnect, SQLDelete, SQLExecute, SQLInsert, SQLQuery, SQLUpdate, StartsWith, StaticBaseUri, StaticContextAccessor, StaticContextAccessor.DefaultCollation, StreamAvailable, String_1, StringJoin, StringLength_1, StringToCodepoints, StringValue, StyleElement, Subsequence_2, Subsequence_3, Substring, SubstringAfter, SubstringBefore, Sum, SuperId, SuperId.ElementWithId, SuperId.Id, SystemFunction, SystemFunctionWithBoundContextItem, SystemProperty, TailFn, TextFragmentValue, TextImpl, TextValueTemplateNode, TimeValue, TinyAttributeImpl, TinyDocumentImpl, TinyElementImpl, TinyNodeImpl, TinyParentNodeImpl, TinyTextImpl, TinyTextualElement, TinyTextualElement.TinyTextualElementText, Tokenize_1, Tokenize_3, Trace, TransformFn, Translate, TreatFn, TreatFn.ExactlyOne, TreatFn.OneOrMore, TreatFn.ZeroOrOne, Tuple, TypeAvailable, TypeStrippedNode, UnionCastableFunction, UnionConstructorFunction, Unordered, UnparsedEntity, UnparsedEntity.UnparsedEntityPublicId, UnparsedEntity.UnparsedEntityUri, UnparsedText, UnparsedTextAvailable, UnparsedTextFunction, UnparsedTextLines, UnresolvedXQueryFunctionItem, UntypedAtomicValue, UpperCase, UriCollection, UserFunction, UserFunctionReference.BoundUserFunction, VendorFunctionSetHE.DynamicErrorInfoFn, VendorFunctionSetHE.HasLocalNamespaces, VendorFunctionSetHE.HasUniformNamespaces, VendorFunctionSetHE.IsWholeNumberFn, VirtualCopy, VirtualUntypedCopy, WhitespaceTextImpl, XMLToJsonFn, XOMDocumentWrapper, XOMNodeWrapper, XSLAccept, XSLAcceptExpose, XSLAccumulator, XSLAccumulatorRule, XSLAnalyzeString, XSLApplyImports, XSLApplyTemplates, XSLAssert, XSLAttribute, XSLAttributeSet, XSLBreak, XSLBreakOrContinue, XSLCallTemplate, XSLCatch, XSLCharacterMap, XSLChoose, XSLComment, XSLContextItem, XSLCopy, XSLCopyOf, XSLDecimalFormat, XSLDocument, XSLElement, XSLEvaluate, XSLExpose, XSLFallback, XSLForEach, XSLForEachGroup, XSLFork, XSLFunction, XSLGeneralIncorporate, XSLGeneralVariable, XSLGlobalContextItem, XSLGlobalParam, XSLGlobalVariable, XSLIf, XSLImport, XSLImportSchema, XSLInclude, XSLIterate, XSLKey, XSLLeafNodeConstructor, XSLLocalParam, XSLLocalVariable, XSLMap, XSLMapEntry, XSLMatchingSubstring, XSLMerge, XSLMergeAction, XSLMergeKey, XSLMergeSource, XSLMessage, XSLMode, XSLModuleRoot, XSLNamespace, XSLNamespaceAlias, XSLNextIteration, XSLNextMatch, XSLNumber, XSLOnCompletion, XSLOnEmpty, XSLOnNonEmpty, XSLOtherwise, XSLOutput, XSLOutputCharacter, XSLOverride, XSLPackage, XSLPerformSort, XSLPreserveSpace, XSLProcessingInstruction, XSLResultDocument, XSLSequence, XSLSort, XSLSortOrMergeKey, XSLSourceDocument, XSLStylesheet, XSLTemplate, XSLText, XSLTry, XSLUsePackage, XSLValueOf, XSLWhen, XSLWherePopulated, XSLWithParam, YearMonthDurationValue

public interface Item
extends GroundedValue

An Item is an object that can occur as a member of a sequence. It corresponds directly to the concept of an item in the XPath 2.0 data model. There are four kinds of Item: atomic values, nodes, function items, and external objects.

This interface is part of the public Saxon API. As such (starting from Saxon 8.4), methods that form part of the stable API are labelled with a JavaDoc "since" tag to identify the Saxon release at which they were introduced.

Note: there is no method getItemType(). This is to avoid having to implement it on every implementation of NodeInfo. Instead, use the static method Type.getItemType(Item).

Method Summary

Modifier and Type	Method and Description
AtomicSequence	atomize() Atomize the item.
Genre	getGenre() Get the genre of this item (to distinguish the top-level categories of item, such as nodes, atomic values, and functions)
default int	getLength() Get the size of the value (the number of items)
java.lang.String	getStringValue() Get the value of the item as a string.
java.lang.CharSequence	getStringValueCS() Get the string value of the item as a CharSequence.
default Item	head() Get the first item in the sequence.
default boolean	isStreamed() Ask whether this is a node in a streamed document
default Item	itemAt(int n) Get the n'th item in the value, counting from 0
default SingletonIterator<? extends Item>	iterate() Get an iterator over all the items in the sequence
default GroundedValue	reduce() Reduce the sequence to its simplest form.
default GroundedValue	subsequence(int start, int length) Get a subsequence of the value
static GroundedValue	toGroundedValue(Item item)
default java.lang.String	toShortString() Provide a short string showing the contents of the item, suitable for use in error messages

Methods inherited from interface net.sf.saxon.om.GroundedValue

asIterable, concatenate, containsNode, effectiveBooleanValue, materialize

Methods inherited from interface net.sf.saxon.om.Sequence

makeRepeatable

Method Detail

getGenre

Genre getGenre()

Get the genre of this item (to distinguish the top-level categories of item, such as nodes, atomic values, and functions)

Returns:

the genre

head

default Item head()

Get the first item in the sequence. Differs from the superclass Sequence in that * no exception is thrown.

Specified by:

head in interface GroundedValue

Specified by:

head in interface Sequence

Returns:

the first item in the sequence if there is one, or null if the sequence is empty

getStringValue

java.lang.String getStringValue()

Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.

If the calling code can handle any CharSequence, the method getStringValueCS() should be used. If the caller requires a string, this method is preferred.

Specified by:

getStringValue in interface GroundedValue

Returns:

the string value of the item

Throws:

java.lang.UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValueCS()

getStringValueCS

java.lang.CharSequence getStringValueCS()

Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that X.getStringValueCS().toString() returns a string that is equal to X.getStringValue().

Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the getStringValue() method is preferred.

Specified by:

getStringValueCS in interface GroundedValue

Returns:

the string value of the item

Throws:

java.lang.UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValue()

atomize

AtomicSequence atomize()
                throws XPathException

Atomize the item.

Returns:

the result of atomization

Throws:

XPathException - if atomization is not allowed for this kind of item

toShortString

default java.lang.String toShortString()

Provide a short string showing the contents of the item, suitable for use in error messages

Specified by:

toShortString in interface GroundedValue

Returns:

a depiction of the item suitable for use in error messages

itemAt

default Item itemAt(int n)

Get the n'th item in the value, counting from 0

Specified by:

itemAt in interface GroundedValue

Parameters:

n - the index of the required item, with 0 representing the first item in the sequence

Returns:

the n'th item if it exists, or null otherwise

subsequence

default GroundedValue subsequence(int start,
                                  int length)

Get a subsequence of the value

Specified by:

subsequence in interface GroundedValue

Parameters:

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 returned

length - 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 value goes off the end of the sequence, the result returns items up to the end of the sequence

Returns:

the required subsequence. If min is

getLength

default int getLength()

Get the size of the value (the number of items)

Specified by:

getLength in interface GroundedValue

Returns:

the number of items in the sequence. Note that for a single item, including a map or array, the result is always 1 (one).

iterate

default SingletonIterator<? extends Item> iterate()

Get an iterator over all the items in the sequence

Specified by:

iterate in interface GroundedValue

Specified by:

iterate in interface Sequence

Returns:

an iterator over all the items

reduce

default GroundedValue reduce()

Reduce the sequence to its simplest form. If the value is an empty sequence, the result will be EmptySequence.getInstance(). If the value is a single atomic value, the result will be an instance of AtomicValue. If the value is a single item of any other kind, the result will be an instance of Item. Otherwise, the result will typically be unchanged.

Specified by:

reduce in interface GroundedValue

Returns:

the simplified sequence

toGroundedValue

static GroundedValue toGroundedValue(Item item)

isStreamed

default boolean isStreamed()

Ask whether this is a node in a streamed document

Returns:

true if the node is in a document being processed using streaming