Package 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`, `AnalyzeUri`, `AnnotationParent`, `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`, `ArrayMember`, `ArrayMemberValue`, `ArraySort`, `AtomicConstructorFunction`, `AtomicValue`, `AttributeImpl`, `AvailableEnvironmentVariables`, `AvailableSystemProperties`, `Average`, `AxiomAttributeWrapper`, `AxiomDocumentNodeWrapper`, `AxiomElementNodeWrapper`, `AxiomLeafNodeWrapper`, `AxiomParentNodeWrapper`, `Base64BinaryValue`, `BaseUri_1`, `BigDecimalValue`, `BigIntegerValue`, `Bindery.FailureValue`, `BooleanFn`, `BooleanValue`, `CalendarValue`, `CallableFunction`, `Ceiling`, `CharactersFn`, `CodepointEqual`, `CodepointsToString`, `CoercedFunction`, `CollatingFunctionFixed`, `CollatingFunctionFree`, `CollationKeyFn`, `CollectionFn`, `CommentImpl`, `Compare`, `CompileQuery`, `CompileStylesheet`, `CompileXPath`, `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`, `DecimalDivide`, `DecimalValue`, `DeepEqual`, `DeepEqual`, `DelegatingArrayItem`, `DelegatingMapItem`, `DictionaryMap`, `DistinctValues`, `Doc`, `Doc_2`, `DocAvailable`, `DocumentFn`, `DocumentImpl`, `DocumentUri_1`, `DOM4JNodeWrapper`, `DominoAttr`, `DominoNode`, `DOMNodeWrapper`, `DoubleValue`, `DurationValue`, `DynamicContextAccessor`, `DynamicContextAccessor.CurrentDate`, `DynamicContextAccessor.CurrentDateTime`, `DynamicContextAccessor.CurrentTime`, `DynamicContextAccessor.DefaultLanguage`, `DynamicContextAccessor.ImplicitTimezone`, `ElementAvailable`, `ElementImpl`, `Empty`, `EncodeForUri`, `Ending`, `Ending.ItemsBefore`, `Ending.ItemsUntil`, `EndsWith`, `EnvironmentVariable`, `EQName`, `Error`, `EscapeHtmlUri`, `Eval`, `Evaluate`, `Exists`, `EXPathFileFunctionSet.BaseDir`, `ExpressionFn`, `ExsltCommonFunctionSet.NodeSetFn`, `ExsltCommonFunctionSet.ObjectTypeFn`, `ExtensionInstruction`, `FilterFn`, `FleetingDocumentNode`, `FleetingElementNode`, `FleetingNode`, `FleetingParentNode`, `FloatValue`, `Floor`, `FoldingFunction`, `FoldLeftFn`, `FoldRightFn`, `ForEachFn`, `ForEachPairFn`, `FormatDate`, `FormatInteger`, `FormatNumber`, `FunctionAnnotations`, `FunctionArity`, `FunctionAvailable`, `FunctionLookup`, `FunctionName`, `GDateValue`, `GDayValue`, `GenerateId_1`, `GMonthDayValue`, `GMonthValue`, `GroupStarting`, `GYearMonthValue`, `GYearValue`, `HasChildren_1`, `HashTrieMap`, `HeadFn`, `HexBinaryValue`, `HighestOrLowest`, `Idref`, `ImmutableArrayItem`, `Index`, `IndexOf`, `IndexWhere`, `Innermost`, `InScopeNamespacesFn`, `InScopePrefixes`, `InsertBefore`, `Int64Value`, `IntegerValue`, `IriToUri`, `IsNaN`, `IXSLFunctionSet.Call`, `IXSLFunctionSet.Eval`, `IXSLFunctionSet.ScheduleActionFn`, `IXSLFunctionSet.Source`, `IXSLFunctionSet.Stub`, `IXSLRemoveAttribute`, `IXSLRemoveProperty`, `IXSLScheduleAction`, `IXSLSetAttribute`, `IXSLSetProperty`, `IXSLSetStyle`, `JDOM2NodeWrapper`, `JsonDoc`, `JsonToXMLFn`, `KeyFn`, `KeyMap`, `Lang`, `LastModified`, `Leading`, `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`, `MapSearch`, `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`, `MessageCount`, `Minimax`, `Minimax.Max`, `Minimax.Min`, `Name_1`, `NamespaceForPrefix`, `NamespaceNode`, `NamespaceUri_1`, `NestedIntegerValue`, `NewAttribute`, `NewComment`, `NewDocument`, `NewElement`, `NewNamespace`, `NewProcessingInstruction`, `NewText`, `Nilled_1`, `NodeImpl`, `NodeName_1`, `NormalizeSpace_1`, `NormalizeUnicode`, `NotationValue`, `NotFn`, `Number_1`, `NumericValue`, `ObjectMap`, `ObjectValue`, `OriginalFunction`, `Orphan`, `Outermost`, `ParentNodeImpl`, `Parse`, `ParseHtml`, `ParseIetfDate`, `ParseJsonFn`, `ParseXml`, `ParseXmlFragment`, `ParseXPath`, `Path_1`, `PedigreeArrayItem`, `PedigreeFn`, `PedigreeMapItem`, `PositionAndLast`, `PositionAndLast.Last`, `PositionAndLast.Position`, `ProcInstImpl`, `Put`, `QNameFn`, `QNameValue`, `QualifiedNameValue`, `QueryFn`, `RandomNumberGenerator`, `RangeKey`, `RebasedNode`, `RegexFunction`, `RegexFunctionSansFlags`, `RegexGroup`, `Remove`, `Replace`, `ReplaceWith`, `ResolveQName`, `ResolveURI`, `Reverse`, `Root_1`, `Round`, `RoundHalfToEven`, `SaxonArray`, `SaxonArrayMemberInst`, `SaxonAssign`, `SaxonChange`, `SaxonDeepUpdate`, `SaxonDelete`, `SaxonDo`, `SaxonDoctype`, `SaxonEntityRef`, `SaxonForEachMember`, `SaxonImportQuery`, `SaxonInsert`, `SaxonItemType`, `SaxonParam`, `SaxonPreprocess`, `SaxonRename`, `SaxonReplace`, `SaxonTabulateMaps`, `SaxonUpdate`, `SaxonWhile`, `ScalarSystemFunction`, `SchemaElement`, `SchemaFn`, `SendMail`, `Serialize`, `Serialize`, `SimpleArrayItem`, `SingleEntryMap`, `SnapshotFn`, `SnapshotNode`, `Sort_1`, `Sort_2`, `Sort_3`, `SpaceStrippedNode`, `SQLClose`, `SQLColumn`, `SQLConnect`, `SQLConnectFn`, `SQLDelete`, `SQLDeleteFn`, `SQLExecute`, `SQLExecuteFn`, `SQLInsert`, `SQLInsertFn`, `SQLPreparedQueryFn`, `SQLPreparedStatementFn`, `SQLQuery`, `SQLQueryFn`, `SQLTableFn`, `SQLUpdate`, `SQLUpdateFn`, `Starting`, `Starting.ItemsAfter`, `Starting.ItemsFrom`, `StartsWith`, `StaticBaseUri`, `StaticContextAccessor`, `StaticContextAccessor.DefaultCollation`, `StreamableUserFunction`, `StreamAvailable`, `StreamFn`, `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`, `TimestampFn`, `TimeValue`, `TinyAttributeImpl`, `TinyDocumentImpl`, `TinyElementImpl`, `TinyNodeImpl`, `TinyParentNodeImpl`, `TinyTextImpl`, `TinyTextualElement`, `TinyTextualElement.TinyTextualElementText`, `Tokenize_1`, `Tokenize_3`, `Trace`, `TransformFn`, `TransformFn`, `Translate`, `TreatFn`, `TreatFn.ExactlyOne`, `TreatFn.OneOrMore`, `TreatFn.ZeroOrOne`, `Tuple`, `TypeAvailable`, `TypeStrippedNode`, `UnionCastableFunction`, `UnionConstructorFunction`, `UnknownElement`, `Unordered`, `UnparsedEntity`, `UnparsedEntity.UnparsedEntityPublicId`, `UnparsedEntity.UnparsedEntityUri`, `UnparsedText`, `UnparsedTextAvailable`, `UnparsedTextFunction`, `UnparsedTextLines`, `UnresolvedXQueryFunctionItem`, `UntypedAtomicValue`, `UpperCase`, `UriCollection`, `UserFunction`, `UserFunctionReference.BoundUserFunction`, `ValidateFn`, `VendorFunctionSetHE.DynamicErrorInfoFn`, `VendorFunctionSetHE.HasLocalNamespaces`, `VendorFunctionSetHE.HasUniformNamespaces`, `VendorFunctionSetHE.IsWholeNumberFn`, `VirtualCopy`, `VirtualUntypedCopy`, `WhitespaceTextImpl`, `WithPedigree`, `XMLToJsonFn`, `XOMDocumentWrapper`, `XOMNodeWrapper`, `XSDAlternative`, `XSDAnnotation`, `XSDAny`, `XSDAnyAttribute`, `XSDAssert`, `XSDAttribute`, `XSDAttributeGroup`, `XSDComplexContent`, `XSDComplexContentRestriction`, `XSDComplexType`, `XSDCompositor`, `XSDDefaultOpenContent`, `XSDDocumentation`, `XSDElement`, `XSDExtension`, `XSDFacet`, `XSDFieldOrSelector`, `XSDGroup`, `XSDIdentityConstraint`, `XSDImport`, `XSDInclude`, `XSDList`, `XSDNotation`, `XSDOpenContent`, `XSDOverride`, `XSDRedefine`, `XSDSchema`, `XSDSimpleContent`, `XSDSimpleContentRestriction`, `XSDSimpleType`, `XSDSimpleTypeRestriction`, `XSDUnion`, `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

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | 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