Package net.sf.saxon.expr.instruct

## Class UserFunction

- java.lang.Object
- - net.sf.saxon.expr.instruct.Actor
  - - net.sf.saxon.expr.instruct.UserFunction

- All Implemented Interfaces:
    `javax.xml.transform.SourceLocator`, `Callable`, `ContextOriginator`, `ExpressionOwner`, `Locatable`, `Function`, `GroundedValue`, `Item`, `Sequence`, `Location`, `Traceable`, `TraceableComponent`, `org.xml.sax.Locator`
  Direct Known Subclasses:
    `MemoFunction`, `StreamableUserFunction`

      public class UserFunction
      extends Actor
      implements Function, ContextOriginator, TraceableComponent

  This object represents the compiled form of a user-written function (the source can be either an XSLT stylesheet function or an XQuery function).

  It is assumed that type-checking, of both the arguments and the results, has been handled at compile time. That is, the expression supplied as the body of the function must be wrapped in code to check or convert the result to the required type, and calls on the function must be wrapped at compile time to check or convert the supplied arguments.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `UserFunction.Determinism` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected Evaluator` | `evaluator` |

    - ### Fields inherited from class net.sf.saxon.expr.instruct.Actor

      `body`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `UserFunction()` | Create a user-defined function (the body must be added later)

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `acceptsNodesWithoutAtomization()` | Ask whether any of the declared arguments accept nodes without atomizing them
    `AtomicSequence` | `atomize()` | Atomize the item.
    `Sequence` | `call​(XPathContext context, Sequence[] actualArgs)` | Call this function to return a value.
    `Sequence` | `call​(Sequence[] actualArgs, Controller controller)` | Call this function.
    `void` | `callUpdating​(Sequence[] actualArgs, XPathContextMajor context, PendingUpdateList pul)` | Call an updating function.
    `void` | `computeEvaluationMode()` | Determine the preferred evaluation mode for this function
    `boolean` | `containsTailCalls()` | Determine whether the function contains tail calls (on this or other functions)
    `boolean` | `deepEquals​(Function other, XPathContext context, AtomicComparer comparer, int flags)` | Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
    `boolean` | `effectiveBooleanValue()` | Get the effective boolean value of this sequence
    `void` | `export​(ExpressionPresenter presenter)` | Diagnostic print of expression structure.
    `void` | `gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)` | Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
    `AnnotationList` | `getAnnotations()` | Get the annotations defined on this function
    `SequenceType` | `getArgumentType​(int n)` | Get the required types of an argument to this function
    `int` | `getArity()` | Get the arity of this function
    `SequenceType` | `getDeclaredResultType()` | Get the declared result type
    `FunctionStreamability` | `getDeclaredStreamability()` | Get the declared streamability (XSLT 3.0 attribute)
    `java.lang.String` | `getDescription()` | Get a description of this function for use in error messages.
    `UserFunction.Determinism` | `getDeterminism()` | Get the determinism of the function.
    `Evaluator` | `getEvaluator()` | Get the evaluation mode.
    `FunctionItemType` | `getFunctionItemType()` | Get the type of the function
    `StructuredQName` | `getFunctionName()` | Get the function name
    `int` | `getLength()` | Get the size of the value (the number of items)
    `StructuredQName` | `getObjectName()` | Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
    `OperandRole[]` | `getOperandRoles()` | Get the roles of the arguments, for the purposes of streaming
    `UserFunctionParameter[]` | `getParameterDefinitions()` | Get the definitions of the declared parameters for this function
    `int` | `getReferenceCount()` |
    `SequenceType` | `getResultType()` | Get the type of value returned by this function
    `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.
    `SymbolicName.F` | `getSymbolicName()` | Get the symbolic name of the component
    `java.lang.String` | `getTracingTag()` | Get a string used to identify this kind of component when used in tracing output
    `UserFunction` | `head()` | Get the first item in the sequence.
    `void` | `incrementReferenceCount()` |
    `boolean` | `isArray()` | Ask whether this function item is an array
    `boolean` | `isExportable()` |
    `java.lang.Boolean` | `isInlineable()` | Ask whether the function can be inlined
    `boolean` | `isMap()` | Ask whether this function item is a map
    `boolean` | `isMemoFunction()` | Ask whether this function is a memo function
    `boolean` | `isOverrideExtensionFunction()` |
    `boolean` | `isTailRecursive()` | Determine whether the function contains a tail call, calling itself
    `boolean` | `isTrustedResultType()` | Check that result type is of the trusted system functions to return a result of the correct type
    `boolean` | `isUpdating()` | Ask whether this is an updating function (as defined in XQuery Update)
    `Function` | `itemAt​(int n)` | Get the n'th item in the value, counting from 0
    `XPathContextMajor` | `makeNewContext​(XPathContext oldContext, ContextOriginator originator)` | Create a context for evaluating this function
    `void` | `markAsInlined()` | Indicate that the function is being inlined, incrementing a count of how many times it has been inlined
    `void` | `prepareForStreaming()` |
    `void` | `process​(XPathContextMajor context, Sequence[] actualArgs, Outputter output)` | Call this function in "push" mode, writing the results to the current output destination.
    `UserFunction` | `reduce()` | Reduce the sequence to its simplest form.
    `void` | `setAnnotations​(AnnotationList list)` | Supply a set of annotations
    `void` | `setDeclaredStreamability​(FunctionStreamability streamability)` | Set the declared streamability (XSLT 3.0 attribute)
    `void` | `setDeterminism​(UserFunction.Determinism determinism)` | Set the determinism of the function.
    `void` | `setEvaluationMode​(EvaluationMode mode)` | Set the evaluation mode.
    `void` | `setFunctionName​(StructuredQName name)` | Set the function name
    `void` | `setInlineable​(boolean inlineable)` | Say whether this function can be inlined
    `void` | `setOverrideExtensionFunction​(boolean overrideExtensionFunction)` |
    `void` | `setParameterDefinitions​(UserFunctionParameter[] params)` | Set the definitions of the declared parameters for this function
    `void` | `setResultType​(SequenceType resultType)` | Set the declared result type of the function
    `void` | `setTailRecursive​(boolean tailCalls, boolean recursiveTailCalls)` | Indicate whether the function contains a tail call
    `void` | `setUpdating​(boolean isUpdating)` | Set whether this is an updating function (as defined in XQuery Update)
    `GroundedValue` | `subsequence​(int start, int length)` | Get a subsequence of the value
    `void` | `typeCheck​(ExpressionVisitor visitor)` |

    - ### Methods inherited from class net.sf.saxon.expr.instruct.Actor

      `allocateAllBindingSlots, allocateBindingSlotsRecursive, getBody, getChildExpression, getColumnNumber, getComponentName, getDeclaredVisibility, getDeclaringComponent, getLineNumber, getLocation, getPackageData, getProperties, getProperty, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, makeDeclaringComponent, obtainDeclaringComponent, saveLocation, setBody, setChildExpression, setColumnNumber, setDeclaredVisibility, setDeclaringComponent, setLineNumber, setPackageData, setRetainedStaticContext, setStackFrameMap, setSystemId`

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.om.Function

      `getGenre, toShortString`

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

      `asIterable, concatenate, containsNode, materialize`

    - ### Methods inherited from interface net.sf.saxon.om.Item

      `isStreamed, iterate`

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

      `getLocation`

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

      `makeRepeatable`

    - ### Methods inherited from interface net.sf.saxon.trace.TraceableComponent

      `getBody, setBody`

- - ### Field Detail

    - #### evaluator

          protected Evaluator evaluator

  - ### Constructor Detail

    - #### UserFunction

          public UserFunction()

      Create a user-defined function (the body must be added later)

  - ### Method Detail

    - #### setFunctionName

          public void setFunctionName​(StructuredQName name)

      Set the function name
      Parameters:
        `name` - the function name

    - #### getFunctionName

          public StructuredQName getFunctionName()

      Get the function name
      Specified by:
        `getFunctionName` in interface `Function`
      Returns:
        the function name, as a StructuredQName. Returns null for an anonymous function

    - #### getDescription

          public java.lang.String getDescription()

      Get a description of this function for use in error messages. For named functions, the description is the function name (as a lexical QName). For others, it might be, for example, "inline function", or "partially-applied ends-with function".
      Specified by:
        `getDescription` in interface `Function`
      Returns:
        a description of the function for use in error messages

    - #### getTracingTag

          public java.lang.String getTracingTag()

      Description copied from class: `Actor`
      Get a string used to identify this kind of component when used in tracing output
      Specified by:
        `getTracingTag` in interface `TraceableComponent`
      Overrides:
        `getTracingTag` in class `Actor`
      Returns:
        an identifying string

    - #### gatherProperties

          public void gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)

      Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
      Specified by:
        `gatherProperties` in interface `Traceable`
      Parameters:
        `consumer` - the function to which the properties should be supplied, as (property name, value) pairs.

    - #### getObjectName

          public StructuredQName getObjectName()

      Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.
      Specified by:
        `getObjectName` in interface `Traceable`
      Returns:
        the QName of the object declared or manipulated by this instruction or expression

    - #### getSymbolicName

          public SymbolicName.F getSymbolicName()

      Description copied from class: `Actor`
      Get the symbolic name of the component
      Specified by:
        `getSymbolicName` in class `Actor`
      Returns:
        the symbolic name

    - #### getFunctionItemType

          public FunctionItemType getFunctionItemType()

      Get the type of the function
      Specified by:
        `getFunctionItemType` in interface `Function`
      Returns:
        the function type

    - #### getOperandRoles

          public OperandRole[] getOperandRoles()

      Get the roles of the arguments, for the purposes of streaming
      Specified by:
        `getOperandRoles` in interface `Function`
      Returns:
        an array of OperandRole objects, one for each argument

    - #### acceptsNodesWithoutAtomization

          public boolean acceptsNodesWithoutAtomization()

      Ask whether any of the declared arguments accept nodes without atomizing them
      Returns:
        true if this is the case

    - #### isOverrideExtensionFunction

          public boolean isOverrideExtensionFunction()

    - #### setOverrideExtensionFunction

          public void setOverrideExtensionFunction​(boolean overrideExtensionFunction)

    - #### setAnnotations

          public void setAnnotations​(AnnotationList list)

      Supply a set of annotations
      Parameters:
        `list` - the new set of annotations, which will replace any previous annotations on the function

    - #### getAnnotations

          public AnnotationList getAnnotations()

      Get the annotations defined on this function
      Specified by:
        `getAnnotations` in interface `Function`
      Returns:
        the list of annotations defined on this function

    - #### setDeterminism

          public void setDeterminism​(UserFunction.Determinism determinism)

      Set the determinism of the function. Corresponds to the XSLT 3.0 values new-each-time=yes|no|maybe
      Parameters:
        `determinism` - the determinism value for the function

    - #### getDeterminism

          public UserFunction.Determinism getDeterminism()

      Get the determinism of the function. Corresponds to the XSLT 3.0 values new-each-time=yes|no|maybe
      Returns:
        the determinism value for the function

    - #### computeEvaluationMode

          public void computeEvaluationMode()

      Determine the preferred evaluation mode for this function

    - #### isInlineable

          public java.lang.Boolean isInlineable()

      Ask whether the function can be inlined
      Returns:
        true (yes), false (no), or null (don't know)

    - #### setInlineable

          public void setInlineable​(boolean inlineable)

      Say whether this function can be inlined
      Parameters:
        `inlineable` - true or false

    - #### markAsInlined

          public void markAsInlined()

      Indicate that the function is being inlined, incrementing a count of how many times it has been inlined

    - #### setParameterDefinitions

          public void setParameterDefinitions​(UserFunctionParameter[] params)

      Set the definitions of the declared parameters for this function
      Parameters:
        `params` - an array of parameter definitions

    - #### getParameterDefinitions

          public UserFunctionParameter[] getParameterDefinitions()

      Get the definitions of the declared parameters for this function
      Returns:
        an array of parameter definitions

    - #### setResultType

          public void setResultType​(SequenceType resultType)

      Set the declared result type of the function
      Parameters:
        `resultType` - the declared return type

    - #### setTailRecursive

          public void setTailRecursive​(boolean tailCalls,
                                       boolean recursiveTailCalls)

      Indicate whether the function contains a tail call
      Parameters:
        `tailCalls` - true if the function contains a tail call (on any function)
        `recursiveTailCalls` - true if the function contains a tail call (on itself)

    - #### containsTailCalls

          public boolean containsTailCalls()

      Determine whether the function contains tail calls (on this or other functions)
      Returns:
        true if the function contains tail calls

    - #### isTailRecursive

          public boolean isTailRecursive()

      Determine whether the function contains a tail call, calling itself
      Returns:
        true if the function contains a directly-recursive tail call

    - #### setUpdating

          public void setUpdating​(boolean isUpdating)

      Set whether this is an updating function (as defined in XQuery Update)
      Parameters:
        `isUpdating` - true if this is an updating function

    - #### isUpdating

          public boolean isUpdating()

      Ask whether this is an updating function (as defined in XQuery Update)
      Returns:
        true if this is an updating function

    - #### setDeclaredStreamability

          public void setDeclaredStreamability​(FunctionStreamability streamability)

      Set the declared streamability (XSLT 3.0 attribute)
      Parameters:
        `streamability` - the declared streamability (defaults to "unclassified")

    - #### getDeclaredStreamability

          public FunctionStreamability getDeclaredStreamability()

      Get the declared streamability (XSLT 3.0 attribute)
      Returns:
        the declared streamability (defaults to "unclassified")

    - #### getResultType

          public SequenceType getResultType()

      Get the type of value returned by this function
      Returns:
        the declared result type, or the inferred result type if this is more precise

    - #### getDeclaredResultType

          public SequenceType getDeclaredResultType()

      Get the declared result type
      Returns:
        the declared result type

    - #### getArgumentType

          public SequenceType getArgumentType​(int n)

      Get the required types of an argument to this function
      Parameters:
        `n` - identifies the argument in question, starting at 0
      Returns:
        a SequenceType object, indicating the required type of the argument

    - #### getEvaluator

          public Evaluator getEvaluator()

      Get the evaluation mode. The evaluation mode will be computed if this has not already been done
      Returns:
        the computed evaluation mode

    - #### setEvaluationMode

          public void setEvaluationMode​(EvaluationMode mode)

      Set the evaluation mode. (Used when reloading a saved package)
      Parameters:
        `mode` - the evaluation mode

    - #### getArity

          public int getArity()

      Get the arity of this function
      Specified by:
        `getArity` in interface `Function`
      Returns:
        the number of arguments

    - #### isMemoFunction

          public boolean isMemoFunction()

      Ask whether this function is a memo function
      Returns:
        false (overridden in a subclass)

    - #### typeCheck

          public void typeCheck​(ExpressionVisitor visitor)
                         throws XPathException

      Throws:
        `XPathException`

    - #### makeNewContext

          public XPathContextMajor makeNewContext​(XPathContext oldContext,
                                                  ContextOriginator originator)

      Create a context for evaluating this function
      Specified by:
        `makeNewContext` in interface `Function`
      Parameters:
        `oldContext` - the existing context of the caller
        `originator` -
      Returns:
        a new context which should be supplied to the call() method.

    - #### call

          public Sequence call​(XPathContext context,
                               Sequence[] actualArgs)
                        throws XPathException

      Call this function to return a value.
      Specified by:
        `call` in interface `Callable`
      Specified by:
        `call` in interface `Function`
      Parameters:
        `context` - This provides the run-time context for evaluating the function. This should be created using `Function.makeNewContext(XPathContext, ContextOriginator)`. It must be an instance of XPathContextMajor.
        `actualArgs` - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a `Closure` to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      Returns:
        a Value representing the result of the function.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function

    - #### process

          public void process​(XPathContextMajor context,
                              Sequence[] actualArgs,
                              Outputter output)
                       throws XPathException

      Call this function in "push" mode, writing the results to the current output destination.
      Parameters:
        `context` - This provides the run-time context for evaluating the function. It is the caller's responsibility to allocate a "clean" context for the function to use; the context that is provided will be overwritten by the function.
        `actualArgs` - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a `Closure` to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function

    - #### call

          public Sequence call​(Sequence[] actualArgs,
                               Controller controller)
                        throws XPathException

      Call this function. This method allows an XQuery function to be called directly from a Java application. It creates the environment needed to achieve this
      Parameters:
        `actualArgs` - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a `Closure` to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
        `controller` - This provides the run-time context for evaluating the function. A Controller may be obtained by calling `XQueryExpression.newController(net.sf.saxon.query.DynamicQueryContext)`. This may be used for a series of calls on functions defined in the same module as the XQueryExpression.
      Returns:
        a Value representing the result of the function.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function.

    - #### callUpdating

          public void callUpdating​(Sequence[] actualArgs,
                                   XPathContextMajor context,
                                   PendingUpdateList pul)
                            throws XPathException

      Call an updating function.
      Parameters:
        `actualArgs` - the arguments supplied to the function. These must have the correct types required by the function signature (it is the caller's responsibility to check this). It is acceptable to supply a `Closure` to represent a value whose evaluation will be delayed until it is needed. The array must be the correct size to match the number of arguments: again, it is the caller's responsibility to check this.
        `context` - the dynamic evaluation context
        `pul` - the pending updates list, to which the function's update actions are to be added.
      Throws:
        `XPathException` - if a dynamic error occurs while evaluating the function.

    - #### export

          public void export​(ExpressionPresenter presenter)
                      throws XPathException

      Diagnostic print of expression structure. The abstract expression tree is written to the supplied outputstream.
      Specified by:
        `export` in interface `Function`
      Specified by:
        `export` in class `Actor`
      Parameters:
        `presenter` - the expression presenter used to display the structure
      Throws:
        `XPathException`

    - #### isExportable

          public boolean isExportable()

      Overrides:
        `isExportable` in class `Actor`

    - #### isTrustedResultType

          public boolean isTrustedResultType()

      Description copied from interface: `Function`
      Check that result type is of the trusted system functions to return a result of the correct type
      Specified by:
        `isTrustedResultType` in interface `Function`

    - #### isMap

          public boolean isMap()

      Ask whether this function item is a map
      Specified by:
        `isMap` in interface `Function`
      Returns:
        true if this function item is a map, otherwise false

    - #### isArray

          public boolean isArray()

      Ask whether this function item is an array
      Specified by:
        `isArray` in interface `Function`
      Returns:
        true if this function item is an array, otherwise false

    - #### deepEquals

          public boolean deepEquals​(Function other,
                                    XPathContext context,
                                    AtomicComparer comparer,
                                    int flags)
                             throws XPathException

      Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
      Specified by:
        `deepEquals` in interface `Function`
      Parameters:
        `other` - the other function item
        `context` - the dynamic evaluation context
        `comparer` - the object to perform the comparison
        `flags` - options for how the comparison is performed
      Returns:
        true if the two function items are deep-equal
      Throws:
        `XPathException` - if the comparison cannot be performed

    - #### itemAt

          public Function itemAt​(int n)

      Get the n'th item in the value, counting from 0
      Specified by:
        `itemAt` in interface `GroundedValue`
      Specified by:
        `itemAt` in interface `Item`
      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

          public GroundedValue subsequence​(int start,
                                           int length)

      Get a subsequence of the value
      Specified by:
        `subsequence` in interface `GroundedValue`
      Specified by:
        `subsequence` in interface `Item`
      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.

    - #### getLength

          public int getLength()

      Get the size of the value (the number of items)
      Specified by:
        `getLength` in interface `GroundedValue`
      Specified by:
        `getLength` in interface `Item`
      Returns:
        the number of items in the sequence

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue()
                                        throws XPathException

      Get the effective boolean value of this sequence
      Specified by:
        `effectiveBooleanValue` in interface `GroundedValue`
      Returns:
        the effective boolean value
      Throws:
        `XPathException` - if the sequence has no effective boolean value (for example a sequence of two integers)

    - #### reduce

          public UserFunction 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 One. Otherwise, the result will typically be unchanged.
      Specified by:
        `reduce` in interface `GroundedValue`
      Specified by:
        `reduce` in interface `Item`
      Returns:
        the simplified sequence

    - #### head

          public UserFunction 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 `Item`
      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

          public 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`
      Specified by:
        `getStringValue` in interface `Item`
      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

          public 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`
      Specified by:
        `getStringValueCS` in interface `Item`
      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

          public AtomicSequence atomize()
                                 throws XPathException

      Atomize the item.
      Specified by:
        `atomize` in interface `Item`
      Returns:
        the result of atomization
      Throws:
        `XPathException` - if atomization is not allowed for this kind of item

    - #### incrementReferenceCount

          public void incrementReferenceCount()

    - #### getReferenceCount

          public int getReferenceCount()

    - #### prepareForStreaming

          public void prepareForStreaming()
                                   throws XPathException

      Throws:
        `XPathException`