Package net.sf.saxon.functions

Class SystemFunction

    • 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
        Throws:
        java.lang.IllegalArgumentException - if there is no system function with the required name and arity

      • 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
        Throws:
        java.lang.IllegalArgumentException - if there is no system function with the required name and arity

      • 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

      • isSequenceVariadic

        public boolean isSequenceVariadic()
        Description copied from interface: FunctionItem
        Ask whether the function is sequence-variadic (accepts a variable number of arguments)
        Returns:
        true if the function is sequence-variadic; default is false

      • 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
        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, or null indicating that no optimization has taken place
        Throws:
        XPathException - if an error is detected

      • 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

      • 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 - if an error is detected

      • equals

        public boolean equals​(java.lang.Object o)
        Determine whether two functions are equivalent
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode 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
        Returns:
        the item type of the result

      • 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
        Returns:
        the properties

      • 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​(FunctionItem f,
                                   XPathContext context,
                                   Sequence... args)
                            throws XPathException
        Make a dynamic call to a supplied argument function (convenience method for use by implementations)
        Parameters:
        f - the function
        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

      • typeCheckCaller

        public Expression typeCheckCaller​(FunctionCall caller,
                                  ExpressionVisitor visitor,
                                  ContextItemStaticInfo contextInfo)
                           throws XPathException
        Type-check a call on this function
        Parameters:
        caller - the function call expression calling this function
        visitor - the expression visitor
        contextInfo - static context information relating to the call
        Returns:
        a type-checked replacement for the supplied function call
        Throws:
        XPathException - if an error is detected

      • 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:
        call - the system function call (on this function)
        out - the export destination
        Throws:
        XPathException - if a failure occurs (such as an I/O error)

      • 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 - if errors are found in the SEF file

      • 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.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getUniStringArg

        protected UnicodeString getUniStringArg​(Sequence supplied)
                                 throws XPathException
        Helper method to get an argument value as a UnicodeString, in the case where an empty sequence should be treated as a zero-length string
        Parameters:
        supplied - the actual argumetn values supplied
        Returns:
        zero-length string if the input was an empty sequence; otherwise the string value of the first item in the sequence
        Throws:
        XPathException - if the first item in the sequence has no string value (for example, a map)

      • getElaborator

        public Elaborator getElaborator()
        Make an elaborator for a system function call on this function
        Returns:
        a suitable elaborator; or null if no custom elaborator is available