Package net.sf.saxon.om

## Interface Sequence

- All Known Subinterfaces:
    `ArrayItem`, `AtomicSequence`, `ExternalObject<T>`, `Function`, `GroundedValue`, `Item`, `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`, `AtomicArray`, `AtomicConstructorFunction`, `AtomicValue`, `AttributeImpl`, `AvailableEnvironmentVariables`, `AvailableSystemProperties`, `Average`, `AxiomAttributeWrapper`, `AxiomDocumentNodeWrapper`, `AxiomElementNodeWrapper`, `AxiomLeafNodeWrapper`, `AxiomParentNodeWrapper`, `Base64BinaryValue`, `BaseUri_1`, `BigDecimalValue`, `BigIntegerValue`, `Bindery.FailureValue`, `BooleanFn`, `BooleanValue`, `CalendarValue`, `CallableFunction`, `Ceiling`, `Chain`, `CharactersFn`, `Closure`, `CodepointEqual`, `CodepointsToString`, `CoercedFunction`, `CollatingFunctionFixed`, `CollatingFunctionFree`, `CollationKeyFn`, `CollectionFn`, `CommentImpl`, `CompactStringValue`, `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`, `EmptyAtomicSequence`, `EmptySequence`, `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`, `IndexedValue`, `IndexOf`, `IndexWhere`, `Innermost`, `InScopeNamespacesFn`, `InScopePrefixes`, `InsertBefore`, `Int64Value`, `IntegerRange`, `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`, `LazySequence`, `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`, `MemoClosure`, `MemoFunction`, `MemoSequence`, `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`, `One`, `OneOrMore`, `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`, `SearchableValue`, `SendMail`, `SequenceExtent`, `SequenceSlice`, `Serialize`, `Serialize`, `SimpleArrayItem`, `SingleEntryMap`, `SingletonClosure`, `SnapshotFn`, `SnapshotNode`, `Sort_1`, `Sort_2`, `Sort_3`, `SpaceStrippedNode`, `SQLClose`, `SQLColumn`, `SQLConnect`, `SQLConnectFn`, `SQLDelete`, `SQLDeleteFn`, `SQLExecute`, `SQLExecuteFn`, `SQLInsert`, `SQLInsertFn`, `SQLPreparedQueryFn`, `SQLPreparedStatementFn`, `SQLQuery`, `SQLQueryFn`, `SQLTable`, `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`, `ZeroOrMore`, `ZeroOrOne`

      public interface Sequence

  This interface represents an XDM Value, that is, a sequence of items.

  Note that different implementations of Sequence might have very different performance characteristics, though all should exhibit the same behaviour. With some sequences, calling iterate() may trigger evaluation of the logic that computes the sequence, and calling iterate() again may cause re-evaluation.

  Users should avoid assuming that a sequence of length one will always be represented as an instance of Item. If you are confident that the sequence will be of length one, call the head() function to get the first item.

  Since:
    9.5. Generified in 9.9. Generics dropped in 10.0.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Item` | `head()` | Get the first item in the sequence.
    `SequenceIterator` | `iterate()` | Get a `SequenceIterator` over all the items in the sequence
    `default Sequence` | `makeRepeatable()` | Ensure that the sequence is in a form where it can be evaluated more than once.
    `default GroundedValue` | `materialize()` | Create a `GroundedValue` containing the same items as this Sequence.

- - ### Method Detail

    - #### head

          Item head()
             throws XPathException

      Get the first item in the sequence.
      Returns:
        the first item in the sequence if there is one, or null if the sequence is empty
      Throws:
        `XPathException` - in the situation where the sequence is evaluated lazily, and evaluation of the first item causes a dynamic error.

    - #### iterate

          SequenceIterator iterate()
                            throws XPathException

      Get a `SequenceIterator` over all the items in the sequence
      Returns:
        an iterator (specifically, a Saxon `SequenceIterator`, which is not a `Iterator`) over all the items
      Throws:
        `XPathException` - in the situation where the sequence is evaluated lazily, and constructing an iterator over the items causes a dynamic error.

    - #### materialize

          default GroundedValue materialize()
                                     throws XPathException

      Create a `GroundedValue` containing the same items as this Sequence. A `GroundedValue` typically contains the entire sequence in memory; at any rate, it guarantees that the entire sequence can be read without any possibility of XPath dynamic errors arising.
      Returns:
        a `GroundedValue` containing the same items as this Sequence
      Throws:
        `XPathException` - if evaluating the contents of the sequence fails with a dynamic error.

    - #### makeRepeatable

          default Sequence makeRepeatable()
                                   throws XPathException

      Ensure that the sequence is in a form where it can be evaluated more than once. Some sequences (for example `LazySequence` and `Closure` can only be evaluated once, and this operation causes these to be grounded. However, making it repeatable is not the same as making it grounded; it does not flush out all errors. Indeed, lazy evaluation relies on this property, because an expression that has been lifted out of a loop must not be evaluated unless the loop is executed at least once, to prevent spurious errors.
      Returns:
        An equivalent sequence that can be repeatedly evaluated
      Throws:
        `XPathException` - if evaluation fails