net.sf.saxon.functions

Class SystemFunction

java.lang.Object

net.sf.saxon.om.AbstractItem

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, 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, 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, EnvironmentVariable, Error, Evaluate, EXPathFileFunctionSet.BaseDir, ExsltCommonFunctionSet.NodeSetFn, ExsltCommonFunctionSet.ObjectTypeFn, FilterFn, FoldingFunction, FoldRightFn, ForEachFn, ForEachPairFn, FormatDate, FormatInteger, FormatNumber, FunctionAnnotations, FunctionArity, FunctionAvailable, FunctionName, HasChildren_1, HeadFn, HighestOrLowest, Idref, Index, Innermost, InScopePrefixes, InsertBefore, IXSLFunctionSet.Call, IXSLFunctionSet.Eval, 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, 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, Nilled_1, NormalizeUnicode, NotFn, Outermost, Parse, ParseIetfDate, ParseXml, ParseXmlFragment, ParseXPath, Put, QNameFn, QueryFn, RandomNumberGenerator, RegexFunction, RegexFunctionSansFlags, RegexGroup, Remove, ResolveQName, ResolveURI, Reverse, Root_1, Round, RoundHalfToEven, ScalarSystemFunction, SchemaFn, SendMail, Serialize, Serialize, SnapshotFn, Sort_1, 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.IsWholeNumberFn, XMLToJsonFn

public abstract class SystemFunction
extends AbstractFunction

Abstract superclass for calls to functions in the standard function library

Constructor Summary

Constructors

Constructor and Description
SystemFunction()

Method Summary

Modifier and Type	Method and 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.
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 net.sf.saxon.om.AbstractItem

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

Methods inherited from class java.lang.Object

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

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

call, iterate

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

head

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

getLength, head, itemAt, reduce, subsequence

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.