net.sf.saxon.functions

## Class CollatingFunction

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.FunctionCall
    - - net.sf.saxon.functions.SystemFunctionCall
      - - net.sf.saxon.functions.CollatingFunction

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Callable, InstructionInfo, Locator
  Direct Known Subclasses:
    Compare, Contains, DeepEqual, DistinctValues, EndsWith, IndexOf, Minimax, StartsWith, SubstringAfter, SubstringBefore

      public abstract class CollatingFunction
      extends SystemFunctionCall

  Abstract superclass for all functions that take an optional collation argument
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected StringCollator` | `staticCollation`

    - ### Fields inherited from class net.sf.saxon.functions.SystemFunctionCall

      `operation`

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

      `argument`

    - ### 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`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CollatingFunction()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `bindStaticContext(StaticContext env)` Bind aspects of the static context on which the particular function depends
    `void` | `checkArguments(ExpressionVisitor visitor)` Method called during static type checking
    `Expression` | `copy()` Copy an expression.
    `boolean` | `equals(Object o)` Determine whether two expressions are equivalent
    `static String` | `expandCollationURI(String collationName, URI expressionBaseURI)` Expand a collation URI, which may be a relative URI reference
    `protected AtomicComparer` | `getAtomicComparer(StringCollator collator, XPathContext context)` During evaluation, get the pre-allocated atomic comparer if available, or allocate a new one otherwise
    `protected abstract int` | `getCollationArgument()` Get the argument position (0-based) containing the collation name
    `protected StringCollator` | `getCollator(XPathContext context)` Get a collator suitable for comparing strings.
    `protected StringCollator` | `getCollatorFromLastArgument(Sequence[] arguments, int arg, XPathContext context)` Get a collator suitable for comparing strings.
    `URI` | `getExpressionBaseURI()` Get the saved static base URI
    `AtomicComparer` | `getPreAllocatedAtomicComparer()` Get the pre-allocated atomic comparer, if available
    `StringCollator` | `getStaticCollation()` Get the collation if known statically, as a StringCollator object
    `protected void` | `preAllocateComparer(AtomicType type0, AtomicType type1, StaticContext env, boolean NaNequalsNaN)` During static analysis, if types are known and the collation is known, pre-allocate a comparer for comparing atomic values.

    - ### Methods inherited from class net.sf.saxon.functions.SystemFunctionCall

      `addContextDocumentArgument, addDocToPathMap, computeCardinality, computeSpecialProperties, equalOrNull, getContextNode, getConvertingCallable, getDefaultArgumentNode, getDetails, getErrorCodeForTypeErrors, getFunctionItemType, getImplementationMethod, getItemType, getOperation, getRequiredType, iterateSubExpressionInfo, makeSystemFunction, optimize, setDetails, useContextItemAsDefault`

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

      `addExternalFunctionCallToPathMap, checkArgumentCount, explain, getArguments, getDisplayName, getExpressionName, getFunctionName, getNumberOfArguments, hashCode, iterateSubExpressions, preEvaluate, promote, replaceSubExpression, setArguments, setFunctionName, simplify, simplifyArguments, toString, typeCheck`

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

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

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

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

    - ### Methods inherited from interface net.sf.saxon.expr.Callable

      `call`

- - ### Field Detail

    - #### staticCollation

          protected StringCollator staticCollation

  - ### Constructor Detail

    - #### CollatingFunction

          public CollatingFunction()

  - ### Method Detail

    - #### bindStaticContext

          public void bindStaticContext(StaticContext env)
                                 throws XPathException

      Bind aspects of the static context on which the particular function depends
      Overrides:
        `bindStaticContext` in class `SystemFunctionCall`
      Parameters:
        `env` - the static context of the function call
      Throws:
        `XPathException` - if execution with this static context will inevitably fail

    - #### getCollationArgument

          protected abstract int getCollationArgument()

      Get the argument position (0-based) containing the collation name
      Returns:
        the position of the argument containing the collation URI

    - #### checkArguments

          public void checkArguments(ExpressionVisitor visitor)
                              throws XPathException

      Description copied from class: `SystemFunctionCall`
      Method called during static type checking
      Overrides:
        `checkArguments` in class `SystemFunctionCall`
      Parameters:
        `visitor` - the expression visitor
      Throws:
        `XPathException` - if the arguments are incorrect

    - #### getExpressionBaseURI

          public URI getExpressionBaseURI()

      Get the saved static base URI
      Returns:
        the static base URI

    - #### getStaticCollation

          public StringCollator getStaticCollation()

      Get the collation if known statically, as a StringCollator object
      Returns:
        a StringCollator. Return null if the collation is not known statically.

    - #### copy

          public Expression copy()

      Copy an expression. This makes a deep copy.
      Overrides:
        `copy` in class `SystemFunctionCall`
      Returns:
        the copy of the original expression

    - #### equals

          public boolean equals(Object o)

      Determine whether two expressions are equivalent
      Overrides:
        `equals` in class `SystemFunctionCall`

    - #### getCollator

          protected StringCollator getCollator(XPathContext context)
                                        throws XPathException

      Get a collator suitable for comparing strings. Returns the collator specified in the given function argument if present, otherwise returns the default collator. This method is called by subclasses at run time.

      This method is used only when evaluating static function calls.

      Parameters:
        `context` - The dynamic context
      Returns:
        a StringCollator
      Throws:
        `XPathException` - if a failure occurs evaluating the collation argument, or if the specified collation is not recognized

    - #### getCollatorFromLastArgument

          protected StringCollator getCollatorFromLastArgument(Sequence[] arguments,
                                                   int arg,
                                                   XPathContext context)
                                                        throws XPathException

      Get a collator suitable for comparing strings. Returns the collator specified in the given function argument if present, otherwise returns the default collator. This method is called by subclasses at run time.

      This method is used only when evaluating dynamic function calls.

      Parameters:
        `arguments` - The arguments supplied to the function call
        `arg` - The position of the argument (base 0) containing the collation name
        `context` - The dynamic context
      Returns:
        a StringCollator
      Throws:
        `XPathException` - if a failure occurs evaluating the collation argument, or if the specified collation is not recognized

    - #### expandCollationURI

          public static String expandCollationURI(String collationName,
                                  URI expressionBaseURI)
                                           throws XPathException

      Expand a collation URI, which may be a relative URI reference
      Parameters:
        `collationName` - the collation URI as provided
        `expressionBaseURI` - the base URI against which the collation URI will be resolved if it is relative
      Returns:
        the resolved (expanded) absolute collation URI
      Throws:
        `XPathException` - if the collation URI cannot be resolved

    - #### preAllocateComparer

          protected void preAllocateComparer(AtomicType type0,
                                 AtomicType type1,
                                 StaticContext env,
                                 boolean NaNequalsNaN)

      During static analysis, if types are known and the collation is known, pre-allocate a comparer for comparing atomic values. Called by some collating functions during type-checking
      Parameters:
        `type0` - the type of the first comparand
        `type1` - the type of the second comparand
        `env` - the static context
        `NaNequalsNaN` - true if two NaN values are to be considered equal

    - #### getPreAllocatedAtomicComparer

          public AtomicComparer getPreAllocatedAtomicComparer()

      Get the pre-allocated atomic comparer, if available
      Returns:
        the preallocated atomic comparer, or null

    - #### getAtomicComparer

          protected AtomicComparer getAtomicComparer(StringCollator collator,
                                         XPathContext context)

      During evaluation, get the pre-allocated atomic comparer if available, or allocate a new one otherwise
      Returns:
        the pre-allocated comparer if one is available; otherwise, a newly allocated one, using the specified StringCollator for comparing strings

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