com.saxonica.functions.extfn
Class Extensions

java.lang.Object
  extended by com.saxonica.functions.extfn.Extensions

public class Extensions
extends Object

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 the URI http://saxon.sf.net/


Method Summary
static DateTimeValue adjustToCivilTime(XPathContext context, DateTimeValue date, String region)
          Adjust a given date/time to a specified civil time zone, taking account of summer time (daylight savings time) changes, as obtained from the Java database of changes to daylight savings time.
static byte[] base64BinaryToOctets(Base64BinaryValue in)
          Convert a base64Binary value to a sequence of integers representing the octets contained in the value
static String base64BinaryToString(XPathContext context, Base64BinaryValue in, String encoding)
          Convert a base64Binary value to a String, assuming a particular encoding
static int columnNumber(NodeInfo node)
          Return the column number of the specified node.
static int columnNumber(XPathContext c)
          Return the column number of the context node.
static QNameValue currentModeName(XPathContext context)
          Get the current mode.
static BigDecimal decimalDivide(BigDecimal arg1, BigDecimal arg2, int scale)
          Perform decimal division to a user-specified precision
static DocumentInfo discardDocument(XPathContext context, DocumentInfo doc)
          Remove a document from the document pool.
static StringValue generateId(NodeInfo node)
          The function saxon:generate-id() is equivalent to the standard XSLT function generate-id().
static Configuration getConfiguration(XPathContext c)
          Return the Configuration object
static XPathContext getContext(XPathContext c)
          Return the XPathContext object
static Controller getController(XPathContext c)
          Return the Controller object
static String getPseudoAttribute(XPathContext c, String name)
          Get a pseudo-attribute of a processing instruction.
static boolean hasSameNodes(SequenceIterator p1, SequenceIterator p2)
          Determine whether two node-sets contain the same sequences of nodes, compared by identity
static byte[] hexBinaryToOctets(HexBinaryValue in)
          Convert a hexBinary value to a sequence of integers representing the octets contained in the value
static String hexBinaryToString(XPathContext context, HexBinaryValue in, String encoding)
          Convert a hexBinary value to a String, assuming a particular encoding
static 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 int lineNumber(NodeInfo node)
          Return the line number of the specified node.
static int lineNumber(XPathContext c)
          Return the line number of the context node.
static 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 value
static HexBinaryValue octetsToHexBinary(byte[] in)
          Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary value
static String path(XPathContext c)
          Return an XPath expression that identifies the current node
static String path(XPathContext context, NodeInfo node)
          Return an XPath expression that identifies a specified node
static void pauseTracing(XPathContext c)
          Switch tracing off.
static String printStack(XPathContext c)
          Return a string containing a diagnostic print of the current execution stack
static void resumeTracing(XPathContext c)
          Resume tracing.
static Base64BinaryValue stringToBase64Binary(String in, String encoding)
          Convert a string to a base64Binary value in a given encoding
static HexBinaryValue stringToHexBinary(String in, String encoding)
          Convert a string to a hexBinary value in a given encoding
static List stringToUtf8(String in)
          Get the UTF-8 encoding of a string
static String systemId(XPathContext c)
          Return the system identifier of the context node
static QNameValue typeAnnotation(XPathContext context, Item item)
          Determine the value of the type annotation of a node or an atomic value
static String[] unparsedEntities(DocumentInfo doc)
          Get a list of the names of the unparsed entities in a document
static boolean validCharacter(XPathContext c, int in)
          Test whether a given integer is the codepoint of a valid XML character
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

pauseTracing

public static void pauseTracing(XPathContext c)
Switch tracing off. Only works if tracing was enabled at compile time.

Parameters:
c - the XPath dynamic context

resumeTracing

public static void resumeTracing(XPathContext c)
Resume tracing. Only works if tracing was originally enabled but is currently paused.

Parameters:
c - the XPath dynamic context

systemId

public static String systemId(XPathContext c)
                       throws XPathException
Return the system identifier of the context node

Parameters:
c - the XPath dynamic context
Returns:
the system ID
Throws:
XPathException

generateId

public static StringValue generateId(NodeInfo node)
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

public static int lineNumber(XPathContext c)
Return the line number of the context node.

Parameters:
c - the XPath dynamic context
Returns:
the line number, or -1 if not available

lineNumber

public static int lineNumber(NodeInfo node)
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

public static int columnNumber(XPathContext c)
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

public static int columnNumber(NodeInfo node)
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

public static DocumentInfo discardDocument(XPathContext context,
                                           DocumentInfo doc)
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

public static boolean hasSameNodes(SequenceIterator p1,
                                   SequenceIterator p2)
                            throws XPathException
Determine whether two node-sets contain the same sequences of nodes, compared by identity

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

path

public static String path(XPathContext context,
                          NodeInfo node)
                   throws XPathException
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

public static String path(XPathContext c)
                   throws XPathException
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

public static QNameValue typeAnnotation(XPathContext context,
                                        Item item)
Determine the value of the type annotation of a node or an atomic value

Parameters:
context - the XPath dynamic context
item - the node or atomic value whose type annotation is required
Returns:
the type annotation or type label as a QName; null in the case of text nodes, comments, processing instructions

getContext

public static XPathContext getContext(XPathContext c)
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

public static Controller getController(XPathContext c)
Return the Controller object

Parameters:
c - the XPath dynamic context
Returns:
the Controller

getConfiguration

public static Configuration getConfiguration(XPathContext c)
Return the Configuration object

Parameters:
c - the XPath dynamic context
Returns:
the Saxon configuration

printStack

public static String printStack(XPathContext c)
Return a string containing a diagnostic print of the current execution stack

Parameters:
c - the XPath dynamic context
Returns:
a diagnostic stack print

getPseudoAttribute

public static String getPseudoAttribute(XPathContext c,
                                        String name)
                                 throws XPathException
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

public static BigDecimal decimalDivide(BigDecimal arg1,
                                       BigDecimal arg2,
                                       int scale)
Perform decimal division to a user-specified precision

Parameters:
arg1 - the numerator
arg2 - the denominator
scale - the required number of digits in the result of the division
Returns:
the result of the division

stringToUtf8

public static List stringToUtf8(String in)
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

public static Base64BinaryValue octetsToBase64Binary(byte[] in)
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

public static HexBinaryValue octetsToHexBinary(byte[] in)
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

public static byte[] base64BinaryToOctets(Base64BinaryValue in)
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

public static byte[] hexBinaryToOctets(HexBinaryValue in)
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 context
in - the supplied base64Binary value
encoding - 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

public static Base64BinaryValue stringToBase64Binary(String in,
                                                     String encoding)
                                              throws IOException
Convert a string to a base64Binary value in a given encoding

Parameters:
in - the input string
encoding - 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 context
in - the supplied hexBinary value
encoding - 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

public static HexBinaryValue stringToHexBinary(String in,
                                               String encoding)
                                        throws Exception
Convert a string to a hexBinary value in a given encoding

Parameters:
in - the input string
encoding - 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

public static boolean validCharacter(XPathContext c,
                                     int in)
Test whether a given integer is the codepoint of a valid XML character

Parameters:
c - the XPath dynamic context
in - 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 context
prefix - the name of the namespace node
uri - the string value of the namespace node
Returns:
the newly constructed namespace node
Throws:
XPathException

unparsedEntities

public static String[] unparsedEntities(DocumentInfo doc)
                                 throws XPathException
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

inSummerTime

public static 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. 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 timezone
date - the date/time in question. This should preferably include a timezone offset. If it does not, the implicit timezone from the dynamic context is used.
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 an empty sequence was supplied for the dateTime argument, or if no information is available.

adjustToCivilTime

public static DateTimeValue adjustToCivilTime(XPathContext context,
                                              DateTimeValue date,
                                              String region)
Adjust a given date/time to a specified civil time zone, taking account of summer time (daylight savings time) changes, as obtained from 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 timezone
date - the date/time in question. This should preferably include a timezone offset. If it does not, the implicit timezone from the dynamic context is used.
region - An Olsen timezone name such as "America/New_York" or "Europe/Lisbon".
Returns:
The date/time adjusted to the timezone offset applicable to the place denoted by the Olsen timezone name. For example:

adjust-to-civil-time(xs:dateTime('2008-01-10T12:00:00Z', 'America/New_York') returns 2008-01-10T07:00:00-05:00

adjust-to-civil-time(xs:dateTime('2008-07-10T12:00:00Z', 'America/New_York') returns 2008-07-10T08:00:00-04:00


currentModeName

public static QNameValue currentModeName(XPathContext context)
Get the current mode. Returms the name of the current mode if there is one. Returns null (delivered as an empty sequence) if there is no current mode or if the current mode is the unnamed (default) mode.



Copyright (c) 2004-2011 Saxonica Limited. All rights reserved.