net.sf.saxon.expr

## Class FirstItemExpression

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.UnaryExpression
    - - net.sf.saxon.expr.SingleItemFilter
      - - net.sf.saxon.expr.FirstItemExpression

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, InstructionInfo, Locator

      public final class FirstItemExpression
      extends SingleItemFilter

  A FirstItemExpression returns the first item in the sequence returned by a given base expression
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.expr.UnaryExpression

      `operand`

    - ### Fields inherited from class net.sf.saxon.expr.Expression

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, EVENT_FEED_METHOD, INHERITED_CONTEXT, INSPECTION_CONTEXT, ITEM_FEED_METHOD, ITERATE_METHOD, locationId, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, NAVIGATION_CONTEXT, NODE_VALUE_CONTEXT, PROCESS_METHOD, PUSH_SELECTION, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, W3C_CONSUMING, W3C_FREE_RANGING, W3C_GROUP_CONSUMING, W3C_MOTIONLESS, WATCH_METHOD`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Expression` | `copy()` Copy an expression.
    `Item` | `evaluateItem(XPathContext context)` Evaluate the expression
    `ExpressionCompiler` | `getExpressionCompiler()` Return the compiler of the FirstItem expression
    `String` | `getExpressionName()` Get a name identifying the kind of expression, in terms meaningful to a user.
    `int` | `getStreamability(int syntacticContext, boolean allowExtensions, List<String> reasons)` Get the "sweep" of this expression as defined in the W3C streamability specifications.
    `FirstItemExpressionAdjunct` | `getStreamingAdjunct()` Get a class that supports streamed evaluation of this expression
    `static Expression` | `makeFirstItemExpression(Expression base)` Static factory method
    `Pattern` | `toPattern(Configuration config, boolean is30)` Convert this expression to an equivalent XSLT pattern
    `Pattern` | `toStreamingPattern(Configuration config, List<String> reasonForFailure)` Convert this expression to a streaming pattern (a pattern used internally to match nodes during push processing of an event stream)

    - ### Methods inherited from class net.sf.saxon.expr.SingleItemFilter

      `computeCardinality, optimize, promote`

    - ### Methods inherited from class net.sf.saxon.expr.UnaryExpression

      `computeSpecialProperties, displayOperator, equals, explain, getBaseExpression, getItemType, hashCode, iterateSubExpressions, replaceSubExpression, simplify, toString, typeCheck`

    - ### Methods inherited from class net.sf.saxon.expr.Expression

      `addToPathMap, adoptChildExpression, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, doPromotion, dynamicError, effectiveBooleanValue, evaluateAsString, evaluatePendingUpdates, explain, getCardinality, getColumnNumber, getColumnNumber, getConstructType, getContainer, getDependencies, getEvaluationMethod, getExecutable, getHostLanguage, getImplementationMethod, getIntegerBounds, getIntrinsicDependencies, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getObjectName, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getSystemId, getSystemId, hasVariableBinding, implementsStaticTypeCheck, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterate, iterateEvents, iterateSubExpressionInfo, markTailFunctionCalls, process, resetLocalStaticProperties, setContainer, setEvaluationMethod, setFiltered, setFlattened, setLocationId, staticTypeCheck, suppressValidation, typeError`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### makeFirstItemExpression

          public static Expression makeFirstItemExpression(Expression base)

      Static factory method
      Parameters:
        `base` - A sequence expression denoting sequence whose first item is to be returned
      Returns:
        the FirstItemExpression, or an equivalent

    - #### copy

          public Expression copy()

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Returns:
        the copy of the original expression

    - #### toPattern

          public Pattern toPattern(Configuration config,
                          boolean is30)
                            throws XPathException

      Convert this expression to an equivalent XSLT pattern
      Overrides:
        `toPattern` in class `Expression`
      Parameters:
        `config` - the Saxon configuration
        `is30` - true if this is XSLT 3.0
      Returns:
        the equivalent pattern
      Throws:
        `XPathException` - if conversion is not possible

    - #### evaluateItem

          public Item evaluateItem(XPathContext context)
                            throws XPathException

      Evaluate the expression
      Overrides:
        `evaluateItem` in class `Expression`
      Parameters:
        `context` - The context in which the expression is to be evaluated
      Returns:
        the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### getExpressionName

          public String getExpressionName()

      Description copied from class: `Expression`
      Get a name identifying the kind of expression, in terms meaningful to a user.
      Overrides:
        `getExpressionName` in class `Expression`
      Returns:
        a name identifying the kind of expression, in terms meaningful to a user. The name will always be in the form of a lexical XML QName, and should match the name used in explain() output displaying the expression.

    - #### getExpressionCompiler

          public ExpressionCompiler getExpressionCompiler()

      Return the compiler of the FirstItem expression
      Overrides:
        `getExpressionCompiler` in class `Expression`
      Returns:
        the relevant ExpressionCompiler

    - #### getStreamability

          public int getStreamability(int syntacticContext,
                             boolean allowExtensions,
                             List<String> reasons)

      Description copied from class: `Expression`
      Get the "sweep" of this expression as defined in the W3C streamability specifications. This provides an assessment of stylesheet code against the W3C criteria for guaranteed streamability, and is implemented to allow these criteria to be tested. It is not the case that all expression that emerge as streamable from this analysis are currently capable of being streamed by Saxon
      Overrides:
        `getStreamability` in class `Expression`
      Parameters:
        `syntacticContext` - one of the values `Expression.NAVIGATION_CONTEXT`, `Expression.NODE_VALUE_CONTEXT`, `Expression.INHERITED_CONTEXT`, `Expression.INSPECTION_CONTEXT`
        `allowExtensions` - if false, the definition of "guaranteed streamability" in the W3C specification is used. If true, Saxon extensions are permitted, which make some
        `reasons` - the caller may supply a list, in which case the implementation may add to this list a message explaining why the construct is not streamable, suitable for inclusion in an error message.
      Returns:
        one of the values `Expression.W3C_MOTIONLESS`, `Expression.W3C_CONSUMING`, `Expression.W3C_GROUP_CONSUMING`, `Expression.W3C_FREE_RANGING`

    - #### getStreamingAdjunct

          public FirstItemExpressionAdjunct getStreamingAdjunct()

      Description copied from class: `Expression`
      Get a class that supports streamed evaluation of this expression
      Overrides:
        `getStreamingAdjunct` in class `Expression`
      Returns:
        the relevant StreamingAdjunct, or null if none is available

    - #### toStreamingPattern

          public Pattern toStreamingPattern(Configuration config,
                                   List<String> reasonForFailure)

      Convert this expression to a streaming pattern (a pattern used internally to match nodes during push processing of an event stream)
      Overrides:
        `toStreamingPattern` in class `Expression`
      Parameters:
        `config` - the Saxon configuration
        `reasonForFailure` - a list which will be populated with messages giving reasons why the expression cannot be converted
      Returns:
        the equivalent pattern if conversion succeeds; otherwise null

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.