Package net.sf.saxon.functions
Class Extensions
java.lang.Object
net.sf.saxon.functions.Extensions
This class implements functions that are supplied as standard with SAXON,
but which are not defined in the XSLT or XPath specifications.
To invoke these functions, use a function call of the form prefix:name() where name is the method name, and prefix maps to a URI such as http://saxon.sf.net/net.sf.saxon.functions.Extensions (only the part of the URI after the last slash is important).
-
Method Summary
Modifier and TypeMethodDescriptionstatic SequenceIterator
after
(XPathContext context, SequenceIterator ns1, SequenceIterator ns2) Find all the nodes in ns1 that are after the first node in ns2.static byte[]
Convert a base64Binary value to a sequence of integers representing the octets contained in the valuestatic String
base64BinaryToString
(XPathContext context, Base64BinaryValue in, String encoding) Convert a base64Binary value to a String, assuming a particular encodingstatic int
Return the column number of the context node.static int
columnNumber
(NodeInfo node) Return the column number of the specified node.static XQueryExpression
compileQuery
(XPathContext context, String query) Compile a string containing a source query transformationsstatic Templates
compileStylesheet
(XPathContext context, DocumentInfo doc) Compile a document containing a stylesheet module into a stylesheet that can be used to perform transformationsstatic BigDecimal
decimalDivide
(BigDecimal arg1, BigDecimal arg2, int scale) Perform decimal division to a user-specified precisionstatic boolean
deepEqual
(XPathContext context, SequenceIterator arg1, SequenceIterator arg2, String collation, String flags) Perform a parameterized deep-equals() teststatic DocumentInfo
discardDocument
(XPathContext context, DocumentInfo doc) Remove a document from the document pool.static DateTimeValue
fileLastModified
(XPathContext context, String fileURI) This function determines the file modification time.static String
generateId
(NodeInfo node) The function saxon:generate-id() is equivalent to the standard XSLT function generate-id().static Configuration
Return the Configuration objectstatic XPathContext
Return the XPathContext objectstatic Controller
Return the Controller objectstatic String
getPseudoAttribute
(XPathContext c, String name) Get a pseudo-attribute of a processing instruction.static boolean
Determine whether two node-sets contain the same nodesstatic byte[]
Convert a hexBinary value to a sequence of integers representing the octets contained in the valuestatic String
hexBinaryToString
(XPathContext context, HexBinaryValue in, String encoding) Convert a hexBinary value to a String, assuming a particular encodingstatic SequenceIterator
highest
(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) Get the maximum numeric value of a stored expression over a set of nodesstatic Value
highest
(SequenceIterator nsv) Get the node with maximum numeric value of the string-value of each of a set of nodesstatic BooleanValue
inSummerTime
(XPathContext context, DateTimeValue date, String region) Determine whether a given date/time is in summer time (daylight savings time) in a given region.static DateTimeValue
This function implements thelast-modified()
function without any argument.static DateTimeValue
lastModified
(XPathContext context, NodeInfo node) This function implements thelast-modified(node)
function with one argument which must be a node.static SequenceIterator
leading
(XPathContext context, SequenceIterator in, Evaluate.PreparedExpression pexp) Get the items that satisfy the given expression, up to and excluding the first one (in sequence order) that doesn't satisfy the expression.static int
Return the line number of the context node.static int
lineNumber
(NodeInfo node) Return the line number of the specified node.static SequenceIterator
lowest
(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) Get the node with minimum numeric value of the string-value of each of a set of nodesstatic Value
lowest
(SequenceIterator nsv) Get the node with minimum numeric value of the string-value of each of a set of nodesstatic NodeInfo
namespaceNode
(XPathContext context, String prefix, String uri) Create a parentless namespace node.static Base64BinaryValue
octetsToBase64Binary
(byte[] in) Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a base64Binary valuestatic HexBinaryValue
octetsToHexBinary
(byte[] in) Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary valuestatic String
path
(XPathContext c) Return an XPath expression that identifies the current nodestatic String
Return an XPath expression that identifies a specified nodestatic void
Switch tracing off.static String
Return a string containing a diagnostic print of the current execution stackstatic SequenceIterator
query
(XPathContext context, XQueryExpression query) Run a previously-compiled query.static SequenceIterator
query
(XPathContext context, XQueryExpression query, Item source) Run a previously-compiled querystatic SequenceIterator
query
(XPathContext context, XQueryExpression query, Item source, SequenceIterator params) Run a previously-compiled query, supplying parameters to the transformation.static void
Resume tracing.static SequenceIterator
sort
(XPathContext context, SequenceIterator input) Sort a sequence of nodes or atomic values, using the atomic value itself, or the atomized value of the node, as the sort key.static SequenceIterator
sort
(XPathContext context, SequenceIterator input, Evaluate.PreparedExpression sortKeyExpression) Sort a sequence of nodes or atomic values, using a given expression to calculate the sort key.static Base64BinaryValue
stringToBase64Binary
(String in, String encoding) Convert a string to a base64Binary value in a given encodingstatic HexBinaryValue
stringToHexBinary
(String in, String encoding) Convert a string to a hexBinary value in a given encodingstatic List
stringToUtf8
(String in) Get the UTF-8 encoding of a stringstatic String
Return the system identifier of the context nodestatic DocumentInfo
transform
(XPathContext context, Templates templates, NodeInfo source) Run a transformation to convert an input tree to an output documentstatic DocumentInfo
transform
(XPathContext context, Templates templates, NodeInfo source, SequenceIterator params) Run a transformation to convert an input tree to an output document, supplying parameters to the transformation.static QNameValue
typeAnnotation
(XPathContext context, Item item) Display the value of the type annotation of a node or an atomic valuestatic String[]
Get a list of the names of the unparsed entities in a documentstatic boolean
validCharacter
(XPathContext c, int in) Test whether a given integer is the codepoint of a valid XML character
-
Method Details
-
pauseTracing
Switch tracing off. Only works if tracing was enabled at compile time.- Parameters:
c
- the XPath dynamic context
-
resumeTracing
Resume tracing. Only works if tracing was originally enabled but is currently paused.- Parameters:
c
- the XPath dynamic context
-
systemId
Return the system identifier of the context node- Parameters:
c
- the XPath dynamic context- Returns:
- the system ID
- Throws:
XPathException
-
generateId
The function saxon:generate-id() is equivalent to the standard XSLT function generate-id(). It is provided as an extension function to make it available in non-XSLT environments, for example in XQuery.- Parameters:
node
- the node whose identifier is required- Returns:
- as ASCII alphanumeric string that uniquely identifies this node
-
lineNumber
Return the line number of the context node.- Parameters:
c
- the XPath dynamic context- Returns:
- the line number, or -1 if not available
-
lineNumber
Return the line number of the specified node.- Parameters:
node
- the node whose line number is required- Returns:
- the line number of the node. This is only available if line numbering was switched on.
-
columnNumber
Return the column number of the context node. This is only available if line numbering has been enabled for the containing tree- Parameters:
c
- the XPath dynamic context- Returns:
- the column number, or -1 if not available
-
columnNumber
Return the column number of the specified node.- Parameters:
node
- the node whose column number is required- Returns:
- the column number of the node. This is only available if line numbering was switched on.
-
discardDocument
Remove a document from the document pool. The effect is that the document becomes eligible for garbage collection, allowing memory to be released when processing of the document has finished. The downside is that a subsequent call on document() with the same URI causes the document to be reloaded and reparsed, and the new nodes will have different node identity from the old.- Parameters:
context
- the evaluation context (supplied implicitly by the call mechanism)doc
- the document to be released from the document pool- Returns:
- the document that was released. This allows a call such as select="saxon:discard-document(document('a.xml'))"
-
hasSameNodes
Determine whether two node-sets contain the same nodes- Parameters:
p1
- The first node-set. The iterator must be correctly ordered.p2
- The second node-set. The iterator must be correctly ordered.- Returns:
- true if p1 and p2 contain the same set of nodes
- Throws:
XPathException
-
sort
Sort a sequence of nodes or atomic values, using the atomic value itself, or the atomized value of the node, as the sort key. The values must all be comparable. Strings are compared using codepoint collation. When nodes are atomized, the result must not be a sequence containing more than one item.- Parameters:
context
- the XPath dynamic contextinput
- the sequence to be sorted- Returns:
- an iterator over the sorted sequence
-
sort
public static SequenceIterator sort(XPathContext context, SequenceIterator input, Evaluate.PreparedExpression sortKeyExpression) Sort a sequence of nodes or atomic values, using a given expression to calculate the sort key. as the sort key. The values must all be comparable. Strings are compared using codepoint collation. When nodes are atomized, the result must not be a sequence containing more than one item.- Parameters:
context
- the XPath dynamic contextinput
- the sequence to be sortedsortKeyExpression
- the expression used to compute the sort keys- Returns:
- an iterator over the sorted sequence
-
highest
Get the node with maximum numeric value of the string-value of each of a set of nodes- Parameters:
nsv
- the input sequence- Returns:
- the node with the maximum numeric value
- Throws:
XPathException
-
highest
public static SequenceIterator highest(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) throws XPathException Get the maximum numeric value of a stored expression over a set of nodes- Parameters:
context
- the XPath dynamic evaluation contextnsv
- the input sequencepexpression
- the expression whose maximum is to be computed- Returns:
- an iterator over the items in the input sequence for which the expression takes its maximum value
- Throws:
XPathException
-
lowest
Get the node with minimum numeric value of the string-value of each of a set of nodes- Parameters:
nsv
- the input sequence- Returns:
- the node with the minimum numeric value
- Throws:
XPathException
-
lowest
public static SequenceIterator lowest(XPathContext context, SequenceIterator nsv, Evaluate.PreparedExpression pexpression) throws XPathException Get the node with minimum numeric value of the string-value of each of a set of nodes- Parameters:
context
- the XPath dynamic evaluation contextnsv
- the input sequencepexpression
- the expression whose minimum is to be computed- Returns:
- an iterator over the items in the input sequence for which the expression takes its minimum value
- Throws:
XPathException
-
leading
public static SequenceIterator leading(XPathContext context, SequenceIterator in, Evaluate.PreparedExpression pexp) Get the items that satisfy the given expression, up to and excluding the first one (in sequence order) that doesn't satisfy the expression.- Parameters:
context
- the XPath dynamic evaluation contextin
- the input sequencepexp
- the expression against which items are to be tested- Returns:
- an iterator over the items in the input sequence up to and excluding the first one that doesn't satisfy the expression
-
after
public static SequenceIterator after(XPathContext context, SequenceIterator ns1, SequenceIterator ns2) throws XPathException Find all the nodes in ns1 that are after the first node in ns2. Return ns1 if ns2 is empty,- Parameters:
context
- the dynamic evaluation contextns1
- the first operandns2
- the second operand- Returns:
- an iterator over the nodes in ns1 that are after the first node in ns2
- Throws:
XPathException
-
path
Return an XPath expression that identifies a specified node- Parameters:
node
- the node whose path is required- Returns:
- a path expression giving a path from the root of the tree to the specified node
- Throws:
XPathException
-
path
Return an XPath expression that identifies the current node- Parameters:
c
- the XPath dynamic context- Returns:
- a path expression giving a path from the root of the tree to the context node
- Throws:
XPathException
-
typeAnnotation
Display the value of the type annotation of a node or an atomic value- Parameters:
context
- the XPath dynamic contextitem
- the node or atomic value whose type annotation is required- Returns:
- the type annotation or type label as a QName
-
getContext
Return the XPathContext object- Parameters:
c
- the context object- Returns:
- the context object (this looks crazy, but it works given that the function is called from an XPath environment where the context is supplied as an implicit argument)
-
getController
Return the Controller object- Parameters:
c
- the XPath dynamic context- Returns:
- the Controller
-
getConfiguration
Return the Configuration object- Parameters:
c
- the XPath dynamic context- Returns:
- the Saxon configuration
-
printStack
Return a string containing a diagnostic print of the current execution stack- Parameters:
c
- the XPath dynamic context- Returns:
- a diagnostic stack print
-
getPseudoAttribute
Get a pseudo-attribute of a processing instruction. Return an empty string if the pseudo-attribute is not present. Character references and built-in entity references are expanded- Parameters:
c
- the XPath dynamic context. The context item should be a processing instruction, though it doesn't matter if it isn't: the function will look at the string-value of the context item whatever it is.name
- the name of the required pseudo-attribute- Returns:
- the value of the pseudo-attribute if it is present
- Throws:
XPathException
-
decimalDivide
Perform decimal division to a user-specified precision- Parameters:
arg1
- the numeratorarg2
- the denominatorscale
- the required number of digits in the result of the division- Returns:
- the result of the division
-
stringToUtf8
Get the UTF-8 encoding of a string- Parameters:
in
- the supplied string- Returns:
- a sequence of integers, each in the range 0-255, representing the octets of the UTF-8 encoding of the given string
-
octetsToBase64Binary
Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a base64Binary value- Parameters:
in
- the input array of bytes (octets)- Returns:
- the corresponding base64Binary value
-
octetsToHexBinary
Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary value- Parameters:
in
- the input array of bytes (octets)- Returns:
- the corresponding HexBinary value
-
base64BinaryToOctets
Convert a base64Binary value to a sequence of integers representing the octets contained in the value- Parameters:
in
- the supplied base64Binary value- Returns:
- the corresponding array of integers, representing the octet values
-
hexBinaryToOctets
Convert a hexBinary value to a sequence of integers representing the octets contained in the value- Parameters:
in
- the input hexBinary value- Returns:
- the corresponding array of integers, representing the octet values
-
base64BinaryToString
public static String base64BinaryToString(XPathContext context, Base64BinaryValue in, String encoding) throws Exception Convert a base64Binary value to a String, assuming a particular encoding- Parameters:
context
- the XPath dynamic contextin
- the supplied base64Binary valueencoding
- the character encoding- Returns:
- the string that results from treating the base64binary value as a sequence of octets that encode a string in the given encoding
- Throws:
Exception
-
stringToBase64Binary
Convert a string to a base64Binary value in a given encoding- Parameters:
in
- the input stringencoding
- the desired encoding- Returns:
- the base64Binary value that results from encoding the string as a sequence of octets in the given encoding.
- Throws:
IOException
-
hexBinaryToString
public static String hexBinaryToString(XPathContext context, HexBinaryValue in, String encoding) throws Exception Convert a hexBinary value to a String, assuming a particular encoding- Parameters:
context
- the XPath dynamic contextin
- the supplied hexBinary valueencoding
- the character encoding- Returns:
- the string that results from treating the hexBinary value as a sequence of octets that encode a string in the given encoding
- Throws:
Exception
-
stringToHexBinary
Convert a string to a hexBinary value in a given encoding- Parameters:
in
- the input stringencoding
- the desired encoding- Returns:
- the hexBinary value that results from encoding the string as a sequence of octets in the given encoding.
- Throws:
Exception
-
validCharacter
Test whether a given integer is the codepoint of a valid XML character- Parameters:
c
- the XPath dynamic contextin
- the character to be tested- Returns:
- true if and only if the character is valid in (the relevant version of) XML
-
namespaceNode
public static NodeInfo namespaceNode(XPathContext context, String prefix, String uri) throws XPathException Create a parentless namespace node. This function is useful in XQuery when namespaces need to be created dynamically. The effect is the same as that of the xsl:namespace instruction in XSLT.- Parameters:
context
- the dynamic evaluation contextprefix
- the name of the namespace nodeuri
- the string value of the namespace node- Returns:
- the newly constructed namespace node
- Throws:
XPathException
-
unparsedEntities
Get a list of the names of the unparsed entities in a document- Parameters:
doc
- the document node of the document whose unparsed entities are required- Returns:
- an iterator over a sequence of strings containing the names of the unparsed entities
- Throws:
XPathException
-
deepEqual
public static boolean deepEqual(XPathContext context, SequenceIterator arg1, SequenceIterator arg2, String collation, String flags) throws XPathException Perform a parameterized deep-equals() test- Parameters:
context
- The evaluation contextarg1
- The first sequence to be comparedarg2
- The second sequence to be comparedcollation
- The collation to be used (null if the default collation is to be used)flags
- A string whose characters select options that cause the comparison to vary from the standard fn:deep-equals() function. The flags are:- N - take namespace nodes into account
- J - join adjacent text nodes (e.g, nodes either side of a comment)
- A - compare type annotations
- C - take comments into account
- F - take namespace prefixes into account
- P - take processing instructions into account
- S - compare string values, not typed values
- w - don't take whitespace-only text nodes into account
- Returns:
- true if the sequences are deep equal, otherwise false
- Throws:
XPathException
-
lastModified
This function implements thelast-modified()
function without any argument. It returns the modification time of the file containing the context node.- Parameters:
c
- the dynamic evaluation context supplied by Saxon- Returns:
- file modification time as an xs:dateTime value, or an empty sequence if the context item is not a node or if the context node is not present in a local file
- Throws:
XPathException
- XPath dynamic error reported back to Saxon
-
lastModified
This function implements thelast-modified(node)
function with one argument which must be a node. It returns the modification time of the file containing the context node.- Parameters:
node
- the node supplied by a user- Returns:
- file modification time as an xs:dateTime value, or an empty sequence if the supplied node is not present in a local file
- Throws:
XPathException
- if an error occurs and the configuration option TRACE_EXTERNAL_FUNCTIONS is true
-
fileLastModified
public static DateTimeValue fileLastModified(XPathContext context, String fileURI) throws XPathException This function determines the file modification time. It can be called from the stylesheet as file-timestamp(fn).- Parameters:
context
- the XPath dynamic evaluation contextfileURI
- the URI of a file. This must be an absolute URI to which Saxon can connect- Returns:
- file modification time as an xs:dateTime value or an empty sequence if the file is not found
- Throws:
XPathException
- if an error occurs and the configuration option TRACE_EXTERNAL_FUNCTIONS is true
-
inSummerTime
Determine whether a given date/time is in summer time (daylight savings time) in a given region. This relies on the Java database of changes to daylight savings time. Since summer time changes are set by civil authorities the information is not necessarily reliable when applied to dates in the future.- Parameters:
context
- used to get the implicit timezone in the event that the supplied date/time has no timezonedate
- the date/time in question. This should preferably include a timezone.region
- either the two-letter ISO country code, or an Olsen timezone name such as "America/New_York" or "Europe/Lisbon". If the country code denotes a country spanning several timezones, such as the US, then one of them is chosen arbitrarily.- Returns:
- true if the date/time is known to be in summer time in the relevant country; false if it is known not to be in summer time; null if there is no timezone or if no information is available.
-
compileStylesheet
public static Templates compileStylesheet(XPathContext context, DocumentInfo doc) throws XPathException Compile a document containing a stylesheet module into a stylesheet that can be used to perform transformations- Parameters:
context
- the XPath dynamic evaluation contextdoc
- the document containing the stylesheet to be compiled- Returns:
- the compiled stylesheet
- Throws:
XPathException
-
transform
public static DocumentInfo transform(XPathContext context, Templates templates, NodeInfo source) throws XPathException Run a transformation to convert an input tree to an output document- Parameters:
context
- The dynamic contexttemplates
- The compiled stylesheetsource
- The initial context node representing the document to be transformed- Returns:
- the document that results from the transformation
- Throws:
XPathException
-
transform
public static DocumentInfo transform(XPathContext context, Templates templates, NodeInfo source, SequenceIterator params) throws XPathException Run a transformation to convert an input tree to an output document, supplying parameters to the transformation.- Parameters:
context
- The dynamic contexttemplates
- The compiled stylesheetsource
- The initial context node representing the document to be transformedparams
- A sequence of nodes (typically element nodes) supplying values of parameters. The name of the node should match the name of the parameter, the typed value of the node is used as the value of the parameter.- Returns:
- the document that results from the transformation
- Throws:
XPathException
-
compileQuery
public static XQueryExpression compileQuery(XPathContext context, String query) throws XPathException Compile a string containing a source query transformations- Parameters:
context
- the XPath dynamic evaluation contextquery
- a string containing the query to be compiled- Returns:
- the compiled query
- Throws:
XPathException
-
query
public static SequenceIterator query(XPathContext context, XQueryExpression query) throws XPathException Run a previously-compiled query. The initial context item for the query is taken from the context in which the query is called (if there is one); no parameters are supplied- Parameters:
context
- The dynamic contextquery
- The compiled query- Returns:
- the sequence representing the result of the query
- Throws:
XPathException
-
query
public static SequenceIterator query(XPathContext context, XQueryExpression query, Item source) throws XPathException Run a previously-compiled query- Parameters:
context
- The dynamic contextquery
- The compiled querysource
- The initial context item for the query (may be null)- Returns:
- the sequence representing the result of the query
- Throws:
XPathException
-
query
public static SequenceIterator query(XPathContext context, XQueryExpression query, Item source, SequenceIterator params) throws XPathException Run a previously-compiled query, supplying parameters to the transformation.- Parameters:
context
- The dynamic contextquery
- The compiled querysource
- The initial context node for the query (may be null)params
- A sequence of nodes (typically element nodes) supplying values of parameters. The name of the node should match the name of the parameter, the typed value of the node is used as the value of the parameter.- Returns:
- the results of the query (a sequence of items)
- Throws:
XPathException
-