Package net.sf.saxon.functions

Class SystemFunction

java.lang.Object
net.sf.saxon.functions.AbstractFunction
net.sf.saxon.functions.SystemFunction
All Implemented Interfaces:
Callable, FunctionItem, GroundedValue, Item, Sequence
Direct Known Subclasses:
AccumulatorFn, Adjust_1, Adjust_2, Aggregate, AnalyzeUri, ApplyFn, ArrayFunctionSet.ArrayAppend, ArrayFunctionSet.ArrayEmpty, ArrayFunctionSet.ArrayExists, ArrayFunctionSet.ArrayFlatten, ArrayFunctionSet.ArrayFoldLeft, ArrayFunctionSet.ArrayFoldRight, ArrayFunctionSet.ArrayFoot, ArrayFunctionSet.ArrayGeneratingFunction, ArrayFunctionSet.ArrayGet, ArrayFunctionSet.ArrayHead, ArrayFunctionSet.ArrayIndexWhere, ArrayFunctionSet.ArrayInsertBefore, ArrayFunctionSet.ArrayJoin, ArrayFunctionSet.ArrayMembers, ArrayFunctionSet.ArrayPut, ArrayFunctionSet.ArrayRemove, ArrayFunctionSet.ArrayReplace, ArrayFunctionSet.ArraySize, ArrayFunctionSet.ArraySlice, ArrayFunctionSet.ArraySplit, ArrayFunctionSet.ArraySubarray, ArrayFunctionSet.ArrayTail, ArrayFunctionSet.ArrayToSequence, ArrayFunctionSet.ArrayTrunk, AtomicEqual, AvailableEnvironmentVariables, AvailableSystemProperties, BaseUri_1, BooleanFn, CharactersFn, CharactersFn, CharFn, CodepointEqual, CodepointsToString, CollatingFunctionFixed, CollatingFunctionFree, CollectionFn, CompileQuery, CompileStylesheet, CompileXPath, Concat, Concat31, ConstantFunction, ContextAccessorFunction, CopyOfFn, Count, Current, CurrentMergeGroup, CurrentMergeKey, Data_1, DateTimeConstructor, DecimalDivide, DecodeFromURI, Doc, Doc_2, DocAvailable, DocumentFn, DynamicContextAccessor, ElementAvailable, EnvironmentVariable, EQName, Error, EscapeNCName, Evaluate, EveryFn, ExpandedQNameFn, EXPathBinaryFunctionSet.BinaryAnd, EXPathBinaryFunctionSet.BinaryBin, EXPathBinaryFunctionSet.BinaryDecodeString, EXPathBinaryFunctionSet.BinaryEncodeString, EXPathBinaryFunctionSet.BinaryFind, EXPathBinaryFunctionSet.BinaryFromOctets, EXPathBinaryFunctionSet.BinaryHex, EXPathBinaryFunctionSet.BinaryInsertBefore, EXPathBinaryFunctionSet.BinaryJoin, EXPathBinaryFunctionSet.BinaryLength, EXPathBinaryFunctionSet.BinaryNot, EXPathBinaryFunctionSet.BinaryOctal, EXPathBinaryFunctionSet.BinaryOr, EXPathBinaryFunctionSet.BinaryPackDouble, EXPathBinaryFunctionSet.BinaryPackFloat, EXPathBinaryFunctionSet.BinaryPackInteger, EXPathBinaryFunctionSet.BinaryPadLeft, EXPathBinaryFunctionSet.BinaryPadRight, EXPathBinaryFunctionSet.BinaryPart, EXPathBinaryFunctionSet.BinaryShift, EXPathBinaryFunctionSet.BinaryToOctets, EXPathBinaryFunctionSet.BinaryUnpackDouble, EXPathBinaryFunctionSet.BinaryUnpackFloat, EXPathBinaryFunctionSet.BinaryUnpackInteger, EXPathBinaryFunctionSet.BinaryUnpackUnsignedInteger, EXPathBinaryFunctionSet.BinaryVersion, EXPathBinaryFunctionSet.BinaryXor, EXPathFileFunctionSet.FileAppend, EXPathFileFunctionSet.FileAppendBinary, EXPathFileFunctionSet.FileAppendText, EXPathFileFunctionSet.FileAppendTextLines, EXPathFileFunctionSet.FileBaseDir, EXPathFileFunctionSet.FileChildren, EXPathFileFunctionSet.FileCopy, EXPathFileFunctionSet.FileCreateDir, EXPathFileFunctionSet.FileCreateTempDir, EXPathFileFunctionSet.FileCreateTempFile, EXPathFileFunctionSet.FileCurrentDir, EXPathFileFunctionSet.FileDelete, EXPathFileFunctionSet.FileDirSeparator, EXPathFileFunctionSet.FileExists, EXPathFileFunctionSet.FileIsDir, EXPathFileFunctionSet.FileIsFile, EXPathFileFunctionSet.FileLastModified, EXPathFileFunctionSet.FileLineSeparator, EXPathFileFunctionSet.FileList, EXPathFileFunctionSet.FileMove, EXPathFileFunctionSet.FileName, EXPathFileFunctionSet.FileParent, EXPathFileFunctionSet.FilePathSeparator, EXPathFileFunctionSet.FilePathToNative, EXPathFileFunctionSet.FilePathToUri, EXPathFileFunctionSet.FileReadBinary, EXPathFileFunctionSet.FileReadText, EXPathFileFunctionSet.FileReadTextLines, EXPathFileFunctionSet.FileResolvePath, EXPathFileFunctionSet.FileSize, EXPathFileFunctionSet.FileTempDir, EXPathFileFunctionSet.FileWrite, EXPathFileFunctionSet.FileWriteBinary, EXPathFileFunctionSet.FileWriteText, EXPathFileFunctionSet.FileWriteTextLines, ExsltCommonFunctionSet.NodeSetFn, ExsltCommonFunctionSet.ObjectTypeFn, FilterFn, FoldingFunction, FoldRightFn, FootFn, ForEachFn, ForEachPairFn, FormatDate, FormatInteger, FormatNumber, FunctionAnnotations, FunctionArity, FunctionAvailable, FunctionName, GroupStarting, HasChildren_1, HeadFn, HighestOrLowest, HighestOrLowest, IdentityFn, Idref, Index, IndexWhere, Innermost, InScopeNamespacesFn, InScopePrefixes, InsertBefore, Intersperse, IsNaN, ItemsAt, ItemsEnding, ItemsStarting, IterateWhileFn, IXSLFunctionSet.Call, IXSLFunctionSet.Eval, IXSLFunctionSet.ScheduleActionFn, IXSLFunctionSet.Source, IXSLFunctionSet.Stub, JsonDoc, JsonToXMLFn, KeyFn, KeyMap, Lang, LastModified, Leading, LoadXqueryModule, MapCreate, MapFunctionSet.MapBuild, MapFunctionSet.MapContains, MapFunctionSet.MapEntries, MapFunctionSet.MapEntry, MapFunctionSet.MapFilter, MapFunctionSet.MapFind, MapFunctionSet.MapForEach, MapFunctionSet.MapGet, MapFunctionSet.MapKeys, MapFunctionSet.MapMerge, MapFunctionSet.MapOfPairs, MapFunctionSet.MapPair, MapFunctionSet.MapPairs, MapFunctionSet.MapPut, MapFunctionSet.MapRemove, MapFunctionSet.MapSize, MapSearch, MapUntypedContains, MathFunctionSet.Atan2Fn, MathFunctionSet.PiFn, MathFunctionSet.PowFn, MathFunctionSet.TrigFn1, MessageCount, NamespaceForPrefix, NewAttribute, NewComment, NewDocument, NewElement, NewNamespace, NewProcessingInstruction, NewText, Nilled_1, NormalizeUnicode, NotFn, ObjectMap, OpFn, Outermost, ParcelFn, Parse, ParseIetfDate, ParseInteger, ParseQNameFn, ParseXml, ParseXmlFragment, ParseXPath, Partition, Parts, PedigreeFn, Put, QNameFn, QueryFn, RandomNumberGenerator, ReadBinaryResource, RegexFunction, RegexFunctionSansFlags, Remove, Replicate, ResolveQName, ResolveURI, Reverse, Root_1, Round, RoundHalfToEven, SaxonDeepEqual, SaxonSlice, ScalarSystemFunction, SchemaFn, SchemaTypeFn, SendMail, SequenceMatching, Serialize, Serialize, Slice, SnapshotFn, SomeFn, Sort_1, SQLConnectFn, SQLDeleteFn, SQLExecuteFn, SQLInsertFn, SQLPreparedQueryFn, SQLPreparedStatementFn, SQLQueryFn, SQLTableFn, SQLUpdateFn, StaticBaseUri, StaticContextAccessor, StreamAvailable, StreamFn, StringToCodepoints, Subsequence_2, Subsequence_3, Substring, SuperId, SystemProperty, TailFn, TimestampFn, Tokenize_1, Trace, TransformFn, TransformFn, TransitiveClosure, Translate, TreatFn, Trunk, TypeAvailable, UnescapeNCName, Unindexed, Unordered, UnparcelFn, UnparsedEntity, UnparsedTextFunction, UriCollection, URIFunctions, ValidateFn, VendorFunctionSetHE.ArrayAsSequenceOfMaps, VendorFunctionSetHE.ConcatenateSequences, VendorFunctionSetHE.DynamicErrorInfoFn, VendorFunctionSetHE.HasLocalNamespaces, VendorFunctionSetHE.HasUniformNamespaces, VendorFunctionSetHE.IsWholeNumberFn, VendorFunctionSetHE.MapAsSequenceOfMaps, VendorFunctionSetHE.YesNoBoolean, VendorFunctionSetPE.AdjustToCivilTime, VendorFunctionSetPE.Base64BinaryToOctets, VendorFunctionSetPE.Base64BinaryToString, VendorFunctionSetPE.ColumnNumber, VendorFunctionSetPE.ConfigurationFn, VendorFunctionSetPE.ContextFn, VendorFunctionSetPE.ControllerFn, VendorFunctionSetPE.CurrentModeName, VendorFunctionSetPE.DiscardDocument, VendorFunctionSetPE.GetContext, VendorFunctionSetPE.GetPseudoAttribute, VendorFunctionSetPE.HasSameNodes, VendorFunctionSetPE.HexBinaryToOctets, VendorFunctionSetPE.HexBinaryToString, VendorFunctionSetPE.InSummerTime, VendorFunctionSetPE.IsDefaulted, VendorFunctionSetPE.LineNumber, VendorFunctionSetPE.NamespaceNodeFn, VendorFunctionSetPE.OctetsToBase64Binary, VendorFunctionSetPE.OctetsToHexBinary, VendorFunctionSetPE.ParseDateTime, VendorFunctionSetPE.PrintStack, VendorFunctionSetPE.StringToBase64BinaryFn, VendorFunctionSetPE.StringToHexBinaryFn, VendorFunctionSetPE.StringToUTF8, VendorFunctionSetPE.SystemId, VendorFunctionSetPE.TunnelParamsFn, VendorFunctionSetPE.TypeAnnotationFn, VendorFunctionSetPE.UnparsedEntities, VendorFunctionSetPE.ValidCharacter, VoidFn, WithPedigree, XdmToJsonFn, XMLToJsonFn, XQueryFn
public abstract class SystemFunction extends AbstractFunction
Abstract superclass for calls to functions in the standard function library

  • Constructor Details

    • SystemFunction

      public SystemFunction()

  • Method Details

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

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

    • makeFunction40

      public static SystemFunction makeFunction40(String name, RetainedStaticContext rsc, int 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 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 FunctionItem
      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 - if an error is detected

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode 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
      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

    • 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 FunctionItem
      Overrides:
      export in class AbstractFunction
      Parameters:
      out - the destination for the information
      Throws:
      XPathException - if things go wrong

    • 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

    • isTrustedResultType

      public boolean isTrustedResultType()
      Description copied from class: AbstractFunction
      Check that result type is SystemFunction or AtomicConstructorFunction
      Specified by:
      isTrustedResultType in interface FunctionItem
      Overrides:
      isTrustedResultType in class AbstractFunction
      Returns:
      true if the implementation can be trusted

    • 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

    • 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(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 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 String toShortString()
      Provide a short string showing the contents of the item, suitable for use in error messages
      Specified by:
      toShortString in interface FunctionItem
      Specified by:
      toShortString in interface GroundedValue
      Specified by:
      toShortString in interface Item
      Overrides:
      toShortString in class AbstractFunction
      Returns:
      a depiction of the item suitable for use in error messages

    • toString

      public String toString()
      Overrides:
      toString in class 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