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:

PullEvent, Callable, Function, GroundedValue, Item, Sequence

Direct Known Subclasses:

AccumulatorFn, Adjust_1, Adjust_2, Aggregate, ApplyFn, AvailableEnvironmentVariables, AvailableSystemProperties, BaseUri_1, BooleanFn, CodepointEqual, CodepointsToString, CollatingFunctionFixed, CollatingFunctionFree, CollectionFn, CompileTimeFunction, Concat, ConstantFunction, ContextAccessorFunction, CopyOfFn, Current, CurrentGroup, CurrentGroupingKey, CurrentMergeGroup, CurrentMergeKey, CurrentOutputUri, Data_1, DateTimeConstructor, Doc, DocAvailable, DocumentFn, DynamicContextAccessor, ElementAvailable, EnvironmentVariable, Error, FilterFn, FoldingFunction, FoldRightFn, ForEachFn, ForEachPairFn, FormatDate, FormatInteger, FormatNumber, FunctionArity, FunctionAvailable, FunctionName, HasChildren_1, HeadFn, Idref, Innermost, InScopePrefixes, InsertBefore, JsonDoc, JsonToXMLFn, KeyFn, Lang, LoadXqueryModule, NamespaceForPrefix, Nilled_1, NormalizeUnicode, NotFn, Outermost, ParseIetfDate, ParseXml, ParseXmlFragment, Put, QNameFn, RandomNumberGenerator, RegexFunction, RegexFunctionSansFlags, RegexGroup, Remove, ResolveQName, ResolveURI, Reverse, Root_1, Round, RoundHalfToEven, ScalarSystemFunction, Serialize, SerializeJsonFn, SnapshotFn, SortOne, StaticContextAccessor, StreamAvailable, StringToCodepoints, Subsequence_2, Subsequence_3, Substring, SuperId, SystemProperty, TailFn, Tokenize_1, Trace, TransformFn, Translate, TreatFn, TypeAvailable, Unordered, UnparsedEntity, UnparsedTextFunction, UriCollection, XMLToJsonFn, XMLToJsonTransform

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

Methods

Modifier and Type	Method and Description
boolean	equals(Object o) Determine whether two functions are equivalent
void	export(ExpressionPresenter out) Diagnostic print of expression structure.
void	exportAttributes(ExpressionPresenter out) Export any context attributes held within the SystemFunction object.
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
protected NodeInfo	getContextNode(XPathContext context) Helper method for subclasses: get the context item if it is a node, throwing appropriate errors if not
String	getDescription() Get a description of this function for use in error messages.
StandardFunction.Entry	getDetails() Get the details of the function signature
String	getErrorCodeForTypeErrors() Return the error code to be used for type errors.
ExpressionCompiler	getExpressionCompiler() Return the bytecode compiler for a static call to the function in question.
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.
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.
String	getStaticBaseUriString()
StreamingAdjunct	getStreamingAdjunct() Get a class that supports streamed evaluation of this expression
void	importAttributes(Properties attributes) Import any attributes found in the export file, that is, any attributes output using the exportAttributes method
static Expression	makeCall(String name, RetainedStaticContext rsc, Expression... arguments) Make a system function call (one in the standard function namespace).
static SystemFunction	makeFunction(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(StandardFunction.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, getStringValue, getStringValueCS, isArray, isMap, optimize, simplify, typeCheck

Methods inherited from class net.sf.saxon.om.AbstractItem

getLength, head, 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(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(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

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

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

setDetails

public void setDetails(StandardFunction.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 StandardFunction.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 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(Object o)

Determine whether two functions are equivalent

Overrides:

equals in class Object

getErrorCodeForTypeErrors

public 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 if its return type is atomic, or if all its arguments are non-creative. This is overridden for the generate-id() function, which is considered creative if its operand is creative (because the result depends on the identity of the operand)

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

export

public void export(ExpressionPresenter out)

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

typeCheckCaller

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

Typecheck a call on this function

Throws:

XPathException

getStaticBaseUriString

public 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

importAttributes

public void importAttributes(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

getExpressionCompiler

public ExpressionCompiler getExpressionCompiler()

Return the bytecode compiler for a static call to the function in question.

Returns:

the relevant ExpressionCompiler for the corresponding function call

getStreamingAdjunct

public StreamingAdjunct getStreamingAdjunct()

Get a class that supports streamed evaluation of this expression

Returns:

the relevant StreamingAdjunct, or null if none is available