Package net.sf.saxon.functions

## Class SystemFunction

- java.lang.Object
- - net.sf.saxon.functions.AbstractFunction
  - - net.sf.saxon.functions.SystemFunction

- All Implemented Interfaces:
    `Callable`, `Function`, `GroundedValue`, `Item`, `Sequence`
  Direct Known Subclasses:
    `AccumulatorFn`, `Adjust_1`, `Adjust_2`, `Aggregate`, `AnalyzeUri`, `ApplyFn`, `ArrayFunctionSet.ArrayAppend`, `ArrayFunctionSet.ArrayFilter`, `ArrayFunctionSet.ArrayFlatten`, `ArrayFunctionSet.ArrayFoldLeft`, `ArrayFunctionSet.ArrayFoldRight`, `ArrayFunctionSet.ArrayForEach`, `ArrayFunctionSet.ArrayForEachPair`, `ArrayFunctionSet.ArrayGet`, `ArrayFunctionSet.ArrayHead`, `ArrayFunctionSet.ArrayInsertBefore`, `ArrayFunctionSet.ArrayJoin`, `ArrayFunctionSet.ArrayPut`, `ArrayFunctionSet.ArrayRemove`, `ArrayFunctionSet.ArrayReverse`, `ArrayFunctionSet.ArraySize`, `ArrayFunctionSet.ArraySubarray`, `ArrayFunctionSet.ArrayTail`, `ArrayFunctionSet.ArrayToSequence`, `ArrayMember`, `ArraySort`, `AvailableEnvironmentVariables`, `AvailableSystemProperties`, `BaseUri_1`, `BooleanFn`, `CharactersFn`, `CodepointEqual`, `CodepointsToString`, `CollatingFunctionFixed`, `CollatingFunctionFree`, `CollectionFn`, `CompileQuery`, `CompileStylesheet`, `CompileXPath`, `Concat`, `ConstantFunction`, `ContextAccessorFunction`, `CopyOfFn`, `Count`, `Current`, `CurrentGroup`, `CurrentGroupingKey`, `CurrentMergeGroup`, `CurrentMergeKey`, `CurrentOutputUri`, `Data_1`, `DateTimeConstructor`, `DecimalDivide`, `DeepEqual`, `Doc`, `Doc_2`, `DocAvailable`, `DocumentFn`, `DynamicContextAccessor`, `ElementAvailable`, `Ending`, `EnvironmentVariable`, `EQName`, `Error`, `Evaluate`, `EXPathFileFunctionSet.BaseDir`, `ExsltCommonFunctionSet.NodeSetFn`, `ExsltCommonFunctionSet.ObjectTypeFn`, `FilterFn`, `FoldingFunction`, `FoldRightFn`, `ForEachFn`, `ForEachPairFn`, `FormatDate`, `FormatInteger`, `FormatNumber`, `FunctionAnnotations`, `FunctionArity`, `FunctionAvailable`, `FunctionName`, `GroupStarting`, `HasChildren_1`, `HeadFn`, `HighestOrLowest`, `Idref`, `Index`, `IndexWhere`, `Innermost`, `InScopeNamespacesFn`, `InScopePrefixes`, `InsertBefore`, `IsNaN`, `IXSLFunctionSet.Call`, `IXSLFunctionSet.Eval`, `IXSLFunctionSet.ScheduleActionFn`, `IXSLFunctionSet.Source`, `IXSLFunctionSet.Stub`, `JsonDoc`, `JsonToXMLFn`, `KeyFn`, `KeyMap`, `Lang`, `LastModified`, `Leading`, `LoadXqueryModule`, `MapCreate`, `MapFunctionSet.MapContains`, `MapFunctionSet.MapEntry`, `MapFunctionSet.MapFind`, `MapFunctionSet.MapForEach`, `MapFunctionSet.MapGet`, `MapFunctionSet.MapKeys`, `MapFunctionSet.MapMerge`, `MapFunctionSet.MapPut`, `MapFunctionSet.MapRemove`, `MapFunctionSet.MapSize`, `MapSearch`, `MapUntypedContains`, `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`, `MessageCount`, `NamespaceForPrefix`, `NewAttribute`, `NewComment`, `NewDocument`, `NewElement`, `NewNamespace`, `NewProcessingInstruction`, `NewText`, `Nilled_1`, `NormalizeUnicode`, `NotFn`, `ObjectMap`, `Outermost`, `Parse`, `ParseIetfDate`, `ParseXml`, `ParseXmlFragment`, `ParseXPath`, `PedigreeFn`, `Put`, `QNameFn`, `QueryFn`, `RandomNumberGenerator`, `RegexFunction`, `RegexFunctionSansFlags`, `RegexGroup`, `Remove`, `ResolveQName`, `ResolveURI`, `Reverse`, `Root_1`, `Round`, `RoundHalfToEven`, `ScalarSystemFunction`, `SchemaFn`, `SendMail`, `Serialize`, `Serialize`, `SnapshotFn`, `Sort_1`, `SQLConnectFn`, `SQLDeleteFn`, `SQLExecuteFn`, `SQLInsertFn`, `SQLPreparedQueryFn`, `SQLPreparedStatementFn`, `SQLQueryFn`, `SQLTableFn`, `SQLUpdateFn`, `Starting`, `StaticBaseUri`, `StaticContextAccessor`, `StreamAvailable`, `StreamFn`, `StringToCodepoints`, `Subsequence_2`, `Subsequence_3`, `Substring`, `SuperId`, `SystemProperty`, `TailFn`, `TimestampFn`, `Tokenize_1`, `Trace`, `TransformFn`, `TransformFn`, `Translate`, `TreatFn`, `TypeAvailable`, `Unordered`, `UnparsedEntity`, `UnparsedTextFunction`, `UriCollection`, `ValidateFn`, `VendorFunctionSetHE.DynamicErrorInfoFn`, `VendorFunctionSetHE.HasLocalNamespaces`, `VendorFunctionSetHE.HasUniformNamespaces`, `VendorFunctionSetHE.IsWholeNumberFn`, `WithPedigree`, `XMLToJsonFn`

      public abstract class SystemFunction
      extends AbstractFunction

  Abstract superclass for calls to functions in the standard function library

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SystemFunction()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `dependsOnContextItem()` | Ask whether the result of the function depends on the context item
    `static Sequence` | `dynamicCall​(Function f, XPathContext context, Sequence[] args)` | Make a dynamic call to a supplied argument function (convenience method for use by implementations)
    `boolean` | `equals​(java.lang.Object o)` | Determine whether two functions are equivalent
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `void` | `exportAdditionalArguments​(SystemFunctionCall call, ExpressionPresenter out)` | Export any implicit arguments held in optimized form within the SystemFunction call
    `void` | `exportAttributes​(ExpressionPresenter out)` | Export any context attributes held within the SystemFunction object.
    `Expression` | `fixArguments​(Expression... arguments)` | Optimize for constant argument values
    `int` | `getArity()` | Get the arity of the function (the number of arguments).
    `int` | `getCardinality​(Expression[] args)` | Get the cardinality, given knowledge of the actual arguments
    `java.lang.String` | `getCompilerName()` | Get the (local) name of a class that can be used to generate bytecode for this system function
    `protected NodeInfo` | `getContextNode​(XPathContext context)` | Helper method for subclasses: get the context item if it is a node, throwing appropriate errors if not
    `java.lang.String` | `getDescription()` | Get a description of this function for use in error messages.
    `BuiltInFunctionSet.Entry` | `getDetails()` | Get the details of the function signature
    `java.lang.String` | `getErrorCodeForTypeErrors()` | Return the error code to be used for type errors.
    `FunctionItemType` | `getFunctionItemType()` | Get the item type of the function item
    `StructuredQName` | `getFunctionName()` | Get the qualified name of the function being called
    `IntegerValue[]` | `getIntegerBounds()` | For a function that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis.
    `int` | `getNetCost()` | Get an estimate of the net cost of evaluating the function, excluding the cost of evaluating its arguments.
    `OperandRole[]` | `getOperandRoles()` | Get the roles of the arguments, for the purposes of streaming
    `SequenceType` | `getRequiredType​(int arg)` | Get the required type of the nth argument
    `ItemType` | `getResultItemType()` | Determine the item type of the value returned by the function
    `ItemType` | `getResultItemType​(Expression[] args)` | Get the return type, given knowledge of the actual arguments
    `RetainedStaticContext` | `getRetainedStaticContext()` | Get the static context in which the function operates, for use with functions whose result depends on the static context
    `int` | `getSpecialProperties​(Expression[] arguments)` | Determine the special properties of this function.
    `java.lang.String` | `getStaticBaseUriString()` |
    `java.lang.String` | `getStreamerName()` | Get a name that identifies the class that can be used to evaluate this function in streaming mode, that is, supplying one item or event at a time as it is delivered by the parser.
    `void` | `importAttributes​(java.util.Properties attributes)` | Import any attributes found in the export file, that is, any attributes output using the exportAttributes method
    `boolean` | `isTrustedResultType()` | Check that result type is SystemFunction or AtomicConstructorFunction
    `static Expression` | `makeCall​(java.lang.String name, RetainedStaticContext rsc, Expression... arguments)` | Make a system function call (one in the standard function namespace).
    `static SystemFunction` | `makeFunction​(java.lang.String name, RetainedStaticContext rsc, int arity)` | Make a system function item (one in the standard function namespace).
    `Expression` | `makeFunctionCall​(Expression... arguments)` | Make an expression that either calls this function, or that is equivalent to a call on this function
    `Expression` | `makeOptimizedFunctionCall​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo, Expression... arguments)` | Allow the function to create an optimized call based on the values of the actual arguments
    `protected Sequence` | `resultIfEmpty​(int arg)` | Ask if the function always returns a known result when one of the arguments is an empty sequence
    `void` | `setArity​(int arity)` | Set the arity of the function
    `void` | `setDetails​(BuiltInFunctionSet.Entry entry)` | Set the details of this type of function
    `void` | `setRetainedStaticContext​(RetainedStaticContext retainedStaticContext)` | Set the static context in which the function operates, for use with functions whose result depends on the static context
    `void` | `supplyTypeInformation​(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType, Expression[] arguments)` | Method called during static type checking.
    `java.lang.String` | `toShortString()` | Provide a short string showing the contents of the item, suitable for use in error messages
    `java.lang.String` | `toString()` |
    `Expression` | `typeCheckCaller​(FunctionCall caller, ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Typecheck a call on this function

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

      `atomize, deepEquals, effectiveBooleanValue, getAnnotations, getStringValue, getStringValueCS, isArray, isMap, makeNewContext, simplify, typeCheck`

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

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

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

      `call, getGenre`

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

      `asIterable, concatenate, containsNode, materialize`

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

      `getLength, head, isStreamed, itemAt, iterate, reduce, subsequence`

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

      `makeRepeatable`

- - ### Constructor Detail

    - #### SystemFunction

          public SystemFunction()

  - ### Method Detail

    - #### makeCall

          public static Expression makeCall​(java.lang.String name,
                                            RetainedStaticContext rsc,
                                            Expression... arguments)

      Make a system function call (one in the standard function namespace).
      Parameters:
        `name` - The local name of the function.
        `rsc` - Necessary information about the static context
        `arguments` - the arguments to the function call
      Returns:
        a FunctionCall that implements this function, if it exists, or null if the function is unknown.

    - #### makeFunction

          public static SystemFunction makeFunction​(java.lang.String name,
                                                    RetainedStaticContext rsc,
                                                    int arity)

      Make a system function item (one in the standard function namespace).
      Parameters:
        `name` - The local name of the function.
        `rsc` - Necessary information about the static context
        `arity` - the arity of the function
      Returns:
        the function item

    - #### makeFunctionCall

          public Expression makeFunctionCall​(Expression... arguments)

      Make an expression that either calls this function, or that is equivalent to a call on this function
      Parameters:
        `arguments` - the supplied arguments to the function call
      Returns:
        either a function call on this function, or an expression that delivers the same result

    - #### setArity

          public void setArity​(int arity)

      Set the arity of the function
      Parameters:
        `arity` - the number of arguments

    - #### getNetCost

          public int getNetCost()

      Get an estimate of the net cost of evaluating the function, excluding the cost of evaluating its arguments. The result is 0 for very simple functions like position() and exists(), 1 by default, and higher values for particularly expensive functions.
      Returns:
        the estimated cost

    - #### makeOptimizedFunctionCall

          public Expression makeOptimizedFunctionCall​(ExpressionVisitor visitor,
                                                      ContextItemStaticInfo contextInfo,
                                                      Expression... arguments)
                                               throws XPathException

      Allow the function to create an optimized call based on the values of the actual arguments
      Parameters:
        `visitor` - the expression visitor
        `contextInfo` - information about the context item
        `arguments` - the supplied arguments to the function call. Note: modifying the contents of this array should not be attempted, it is likely to have no effect.
      Returns:
        either a function call on this function, or an expression that delivers the same result, or null indicating that no optimization has taken place
      Throws:
        `XPathException` - if an error is detected

    - #### fixArguments

          public Expression fixArguments​(Expression... arguments)
                                  throws XPathException

      Optimize for constant argument values
      Throws:
        `XPathException`

    - #### resultIfEmpty

          protected Sequence resultIfEmpty​(int arg)

      Ask if the function always returns a known result when one of the arguments is an empty sequence
      Parameters:
        `arg` - the argument whose value is an empty sequence (counting from zero)
      Returns:
        the value to be returned when this argument is an empty sequence, or null if unknown / not applicable

    - #### getRetainedStaticContext

          public RetainedStaticContext getRetainedStaticContext()

      Get the static context in which the function operates, for use with functions whose result depends on the static context
      Returns:
        the retained static context

    - #### setRetainedStaticContext

          public void setRetainedStaticContext​(RetainedStaticContext retainedStaticContext)

      Set the static context in which the function operates, for use with functions whose result depends on the static context
      Parameters:
        `retainedStaticContext` - the retained static context

    - #### dependsOnContextItem

          public boolean dependsOnContextItem()

      Ask whether the result of the function depends on the context item
      Returns:
        true if the function depends on the context item

    - #### setDetails

          public void setDetails​(BuiltInFunctionSet.Entry entry)

      Set the details of this type of function
      Parameters:
        `entry` - information giving details of the function signature and other function properties

    - #### getDetails

          public BuiltInFunctionSet.Entry getDetails()

      Get the details of the function signature
      Returns:
        information about the function signature and other function properties

    - #### getFunctionName

          public StructuredQName getFunctionName()

      Get the qualified name of the function being called
      Returns:
        the qualified name

    - #### 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".
      Returns:
        a description of the function for use in error messages

    - #### getArity

          public int getArity()

      Get the arity of the function (the number of arguments). Note that a subclass of SystemFunction may support a family of functions with different arity, but an instance of the SystemFunction class always has a single arity.
      Returns:
        the arity of the function

    - #### getOperandRoles

          public OperandRole[] getOperandRoles()

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

    - #### getIntegerBounds

          public IntegerValue[] getIntegerBounds()

      For a function that returns an integer or a sequence of integers, get a lower and upper bound on the values of the integers that may be returned, from static analysis. The default implementation returns null, meaning "unknown" or "not applicable". Other implementations return an array of two IntegerValue objects, representing the lower and upper bounds respectively. The values UNBOUNDED_LOWER and UNBOUNDED_UPPER are used by convention to indicate that the value may be arbitrarily large. The values MAX_STRING_LENGTH and MAX_SEQUENCE_LENGTH are used to indicate values limited by the size of a string or the size of a sequence.
      Returns:
        the lower and upper bounds of integer values in the result, or null to indicate unknown or not applicable.

    - #### supplyTypeInformation

          public void supplyTypeInformation​(ExpressionVisitor visitor,
                                            ContextItemStaticInfo contextItemType,
                                            Expression[] arguments)
                                     throws XPathException

      Method called during static type checking. This method may be implemented in subclasses so that functions can take advantage of knowledge of the types of the arguments that will be supplied.
      Parameters:
        `visitor` - an expression visitor, providing access to the static context and configuration
        `contextItemType` - information about whether the context item is set, and what its type is
        `arguments` - the expressions appearing as arguments in the function call
      Throws:
        `XPathException`

    - #### equals

          public boolean equals​(java.lang.Object o)

      Determine whether two functions are equivalent
      Overrides:
        `equals` in class `java.lang.Object`

    - #### getErrorCodeForTypeErrors

          public java.lang.String getErrorCodeForTypeErrors()

      Return the error code to be used for type errors. This is overridden for functions such as exactly-one(), one-or-more(), ...
      Returns:
        the error code to be used for type errors in the function call. Normally XPTY0004, but different codes are used for functions such as exactly-one()

    - #### getRequiredType

          public SequenceType getRequiredType​(int arg)

      Get the required type of the nth argument
      Parameters:
        `arg` - the number of the argument whose type is requested, zero-based
      Returns:
        the required type of the argument as defined in the function signature

    - #### getResultItemType

          public ItemType getResultItemType()

      Determine the item type of the value returned by the function

    - #### getFunctionItemType

          public FunctionItemType getFunctionItemType()

      Get the item type of the function item
      Returns:
        the function item's type

    - #### getResultItemType

          public ItemType getResultItemType​(Expression[] args)

      Get the return type, given knowledge of the actual arguments
      Parameters:
        `args` - the actual arguments supplied
      Returns:
        the best available item type that the function will return

    - #### getCardinality

          public int getCardinality​(Expression[] args)

      Get the cardinality, given knowledge of the actual arguments
      Parameters:
        `args` - the actual arguments supplied
      Returns:
        the most precise available cardinality that the function will return

    - #### getSpecialProperties

          public int getSpecialProperties​(Expression[] arguments)

      Determine the special properties of this function. The general rule is that a system function call is non-creative unless more details are defined in a subclass.
      Parameters:
        `arguments` - the actual arguments supplied in a call to the function

    - #### getContextNode

          protected NodeInfo getContextNode​(XPathContext context)
                                     throws XPathException

      Helper method for subclasses: get the context item if it is a node, throwing appropriate errors if not
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        the context item if it exists and is a node
      Throws:
        `XPathException` - if there is no context item or if the context item is not a node

    - #### dynamicCall

          public static Sequence dynamicCall​(Function f,
                                             XPathContext context,
                                             Sequence[] args)
                                      throws XPathException

      Make a dynamic call to a supplied argument function (convenience method for use by implementations)
      Parameters:
        `context` - the XPath dynamic evaluation context
        `args` - the actual arguments to be supplied
      Returns:
        the result of invoking the function
      Throws:
        `XPathException` - if a dynamic error occurs within the function

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

      Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.
      Specified by:
        `export` in interface `Function`
      Overrides:
        `export` in class `AbstractFunction`
      Throws:
        `XPathException`

    - #### typeCheckCaller

          public Expression typeCheckCaller​(FunctionCall caller,
                                            ExpressionVisitor visitor,
                                            ContextItemStaticInfo contextInfo)
                                     throws XPathException

      Typecheck a call on this function
      Throws:
        `XPathException`

    - #### isTrustedResultType

          public boolean isTrustedResultType()

      Description copied from class: `AbstractFunction`
      Check that result type is SystemFunction or AtomicConstructorFunction
      Specified by:
        `isTrustedResultType` in interface `Function`
      Overrides:
        `isTrustedResultType` in class `AbstractFunction`

    - #### getStaticBaseUriString

          public java.lang.String getStaticBaseUriString()

    - #### exportAttributes

          public void exportAttributes​(ExpressionPresenter out)

      Export any context attributes held within the SystemFunction object. The implementation will normally make one or more calls on out.emitAttribute(name, value).
      Parameters:
        `out` - the export destination

    - #### exportAdditionalArguments

          public void exportAdditionalArguments​(SystemFunctionCall call,
                                                ExpressionPresenter out)
                                         throws XPathException

      Export any implicit arguments held in optimized form within the SystemFunction call
      Parameters:
        `out` - the export destination
      Throws:
        `XPathException`

    - #### importAttributes

          public void importAttributes​(java.util.Properties attributes)
                                throws XPathException

      Import any attributes found in the export file, that is, any attributes output using the exportAttributes method
      Parameters:
        `attributes` - the attributes, as a properties object
      Throws:
        `XPathException`

    - #### getCompilerName

          public java.lang.String getCompilerName()

      Get the (local) name of a class that can be used to generate bytecode for this system function
      Returns:
        the name of a bytecode generation class, or null if there is no bytecode support for this function

    - #### getStreamerName

          public java.lang.String getStreamerName()

      Get a name that identifies the class that can be used to evaluate this function in streaming mode, that is, supplying one item or event at a time as it is delivered by the parser. Special streaming support is generally available in Saxon-EE for all system functions that take a sequence as their argument.
      Returns:
        a name that identifies a class that supports streamed evaluation of this system function, or null if no such class is available. The mapping of names to classes is defined in the Saxon-EE class `StreamerMap`. In non-streaming Saxon editions (HE and PE) the method always returns null.

    - #### toShortString

          public java.lang.String toShortString()

      Provide a short string showing the contents of the item, suitable for use in error messages
      Returns:
        a depiction of the item suitable for use in error messages

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`