Extensions

java.lang.Object
- 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

Methods
Modifier and Type	Method and Description
`static ZeroOrOne<DateTimeValue>`	`adjustToCivilTime(XPathContext context, ZeroOrOne<DateTimeValue> date, One<StringValue> 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(One<Base64BinaryValue> in)` Convert a base64Binary value to a sequence of integers representing the octets contained in the value
`static ZeroOrOne<StringValue>`	`base64BinaryToString(XPathContext context, ZeroOrOne<Base64BinaryValue> in, One<StringValue> encoding)` Convert a base64Binary value to a String, assuming a particular encoding
`static One<IntegerValue>`	`columnNumber(XPathContext c)` Return the column number of the context node.
`static One<IntegerValue>`	`columnNumber(ZeroOrOne<NodeInfo> node)` Return the column number of the specified node.
`static ZeroOrOne<QNameValue>`	`currentModeName(XPathContext context)` Get the current mode.
`static ZeroOrOne<DecimalValue>`	`decimalDivide(ZeroOrOne<DecimalValue> arg1, ZeroOrOne<DecimalValue> arg2, One<IntegerValue> scale)` Perform decimal division to a user-specified precision
`static ZeroOrOne<NodeInfo>`	`discardDocument(XPathContext context, ZeroOrOne<NodeInfo> document)` Remove a document from the document pool.
`static ZeroOrMore<Item>`	`eager(ZeroOrMore<Item> value)` Force eager evaluation of the expression supplied as the argument.
`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 One<StringValue>`	`getPseudoAttribute(XPathContext c, One<StringValue> name)` Get a pseudo-attribute of a processing instruction.
`static One<BooleanValue>`	`hasSameNodes(ZeroOrMore<NodeInfo> p1, ZeroOrMore<NodeInfo> p2)` Determine whether two node sequence contain the same sequences of nodes, in the same order, compared by identity
`static byte[]`	`hexBinaryToOctets(One<HexBinaryValue> in)` Convert a hexBinary value to a sequence of integers representing the octets contained in the value
`static ZeroOrOne<StringValue>`	`hexBinaryToString(XPathContext context, ZeroOrOne<HexBinaryValue> in, One<StringValue> encoding)` Convert a hexBinary value to a String, assuming a particular encoding
`static ZeroOrOne<BooleanValue>`	`inSummerTime(XPathContext context, One<DateTimeValue> date, One<StringValue> region)` Determine whether a given date/time is in summer time (daylight savings time) in a given region.
`static ZeroOrOne<BooleanValue>`	`isDefaulted(ZeroOrOne<NodeInfo> arg)` Ask whether an attribute node exists as a result of the expansion of default and fixed values defined in a schema.
`static One<IntegerValue>`	`lineNumber(XPathContext c)` Return the line number of the context node.
`static One<IntegerValue>`	`lineNumber(ZeroOrOne<NodeInfo> node)` Return the line number of the specified node.
`static One<NodeInfo>`	`namespaceNode(XPathContext context, One<StringValue> prefix, One<StringValue> uri)` Create a parentless namespace node.
`static ZeroOrOne<Base64BinaryValue>`	`octetsToBase64Binary(byte[] in)` Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a base64Binary value
`static ZeroOrOne<HexBinaryValue>`	`octetsToHexBinary(byte[] in)` Convert a sequence of integers in the range 0-255, representing a sequence of octets, to a hexBinary value
`static One<StringValue>`	`path(XPathContext c)` Return an XPath expression that identifies the current node
`static One<StringValue>`	`path(XPathContext context, One<NodeInfo> node)` Return an XPath expression that identifies a specified node
`static void`	`pauseTracing(XPathContext c)` Switch tracing off.
`static One<StringValue>`	`printStack(XPathContext c)` Return a string containing a diagnostic print of the current execution stack
`static One<Base64BinaryValue>`	`readBinaryResource(One<StringValue> uri)` Read the contents of a binary resource identified by a URI
`static void`	`resumeTracing(XPathContext c)` Resume tracing.
`static ZeroOrOne<Base64BinaryValue>`	`stringToBase64Binary(ZeroOrOne<StringValue> in, One<StringValue> encoding)` Convert a string to a base64Binary value in a given encoding
`static ZeroOrOne<HexBinaryValue>`	`stringToHexBinary(ZeroOrOne<StringValue> in, One<StringValue> encoding)` Convert a string to a hexBinary value in a given encoding
`static ZeroOrMore<IntegerValue>`	`stringToUtf8(One<StringValue> in)` Get the UTF-8 encoding of a string
`static One<StringValue>`	`systemId(XPathContext c)` Return the system identifier of the context node
`static ZeroOrOne<Function>`	`type(ZeroOrOne<Item> value)` Determine the type annotation of a node or an atomic value in the form of a function item representing the type definition as a schema component, allowing navigation to other related schema components.
`static ZeroOrOne<QNameValue>`	`typeAnnotation(XPathContext context, ZeroOrOne<Item> value)` Determine the value of the type annotation of a node or an atomic value
`static ZeroOrMore<StringValue>`	`unparsedEntities(One<NodeInfo> 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 One<StringValue> 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
  - lineNumber
```
public static One<IntegerValue> 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 One<IntegerValue> lineNumber(ZeroOrOne<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 One<IntegerValue> 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 One<IntegerValue> columnNumber(ZeroOrOne<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 ZeroOrOne<NodeInfo> discardDocument(XPathContext context,
                                  ZeroOrOne<NodeInfo> document)
```
    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)
    document - 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 One<BooleanValue> hasSameNodes(ZeroOrMore<NodeInfo> p1,
                             ZeroOrMore<NodeInfo> p2)
                                      throws XPathException
```
    Determine whether two node sequence contain the same sequences of nodes, in the same order, 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 One<StringValue> path(XPathContext context,
                    One<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 One<StringValue> 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 ZeroOrOne<QNameValue> typeAnnotation(XPathContext context,
                                   ZeroOrOne<Item> value)
```
    Determine the value of the type annotation of a node or an atomic value
    
    Parameters:
    context - the XPath dynamic context
    value - 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
  - type
```
public static ZeroOrOne<Function> type(ZeroOrOne<Item> value)
```
    Determine the type annotation of a node or an atomic value in the form of a function item representing the type definition as a schema component, allowing navigation to other related schema components.
    
    Parameters:
    value - 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 One<StringValue> 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
  - eager
```
public static ZeroOrMore<Item> eager(ZeroOrMore<Item> value)
```
    Force eager evaluation of the expression supplied as the argument.
    
    Parameters:
    value - any value
    
    Returns:
    the supplied value, but in a form that is guaranteed to be "grounded", that is, evaluated in memory with no context dependencies and no possibilities of dynamic evaluation errors when the value is used.
  - getPseudoAttribute
```
public static One<StringValue> getPseudoAttribute(XPathContext c,
                                  One<StringValue> 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 ZeroOrOne<DecimalValue> decimalDivide(ZeroOrOne<DecimalValue> arg1,
                                    ZeroOrOne<DecimalValue> arg2,
                                    One<IntegerValue> scale)
                                             throws XPathException
```
    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
    
    Throws:
    
    XPathException - if scale exceeds the size of an int
  - stringToUtf8
```
public static ZeroOrMore<IntegerValue> stringToUtf8(One<StringValue> 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 ZeroOrOne<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 ZeroOrOne<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(One<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(One<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 ZeroOrOne<StringValue> base64BinaryToString(XPathContext context,
                                          ZeroOrOne<Base64BinaryValue> in,
                                          One<StringValue> encoding)
                                                   throws XPathException
```
    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:
    
    XPathException - for example if the encoding is not recognized or if the binary value is not valid in this encoding.
  - stringToBase64Binary
```
public static ZeroOrOne<Base64BinaryValue> stringToBase64Binary(ZeroOrOne<StringValue> in,
                                                One<StringValue> 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 ZeroOrOne<StringValue> hexBinaryToString(XPathContext context,
                                       ZeroOrOne<HexBinaryValue> in,
                                       One<StringValue> encoding)
                                                throws XPathException
```
    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:
    
    XPathException - if the encoding is not recognized or if the binary value is not valid in this encoding.
  - readBinaryResource
```
public static One<Base64BinaryValue> readBinaryResource(One<StringValue> uri)
                                                 throws XPathException
```
    Read the contents of a binary resource identified by a URI
    
    Parameters:
    uri - the URI of the resource to be read
    
    Returns:
    the contents of the resource identified by the URI, as a Base64Binary value
    
    Throws:
    
    XPathException - if an I/O error occurs, for example if the resource cannot be read
  - stringToHexBinary
```
public static ZeroOrOne<HexBinaryValue> stringToHexBinary(ZeroOrOne<StringValue> in,
                                          One<StringValue> encoding)
                                                   throws XPathException
```
    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:
    
    XPathException - in the event of a dynamic error, for example if the encoding is invalid or the binary value is not valid in this encoding.
  - 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 One<NodeInfo> namespaceNode(XPathContext context,
                          One<StringValue> prefix,
                          One<StringValue> 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 - for example if the prefix is not a valid NCName, or if the URI is empty.
  - unparsedEntities
```
public static ZeroOrMore<StringValue> unparsedEntities(One<NodeInfo> doc)
```
    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:
    a sequence of strings containing the names of the unparsed entities
  - inSummerTime
```
public static ZeroOrOne<BooleanValue> inSummerTime(XPathContext context,
                                   One<DateTimeValue> date,
                                   One<StringValue> 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 ZeroOrOne<DateTimeValue> adjustToCivilTime(XPathContext context,
                                         ZeroOrOne<DateTimeValue> date,
                                         One<StringValue> 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 ZeroOrOne<QNameValue> currentModeName(XPathContext context)
```
    Get the current mode. Returns 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.
    
    Parameters:
    context - the dynamic context
    
    Returns:
    the current mode name, or empty if there is none
  - isDefaulted
```
public static ZeroOrOne<BooleanValue> isDefaulted(ZeroOrOne<NodeInfo> arg)
```
    Ask whether an attribute node exists as a result of the expansion of default and fixed values defined in a schema. Note that this property will only be set if both the configuration properties FeatureKeys.EXPAND_ATTRIBUTE_DEFAULTS and FeatureKeys.MARK_DEFAULTED_ATTRIBUTES are set. The property is currently maintained only for attribute nodes in a TinyTree that results from schema validation, or where DTD-defined defaults are notified by the XML parser.
    
    Parameters:
    arg - the attribute node in question, or null
    
    Returns:
    null if the argument is null; true if the node is an attribute node that exists as a result of the expansion of default and fixed values defined in a schema; provided that configuration options are defined to maintain this property. In all other cases, false.

Class Extensions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

pauseTracing

resumeTracing

systemId

lineNumber

lineNumber

columnNumber

columnNumber

discardDocument

hasSameNodes

path

path

typeAnnotation

type

getContext

getController

getConfiguration

printStack

eager

getPseudoAttribute

decimalDivide

stringToUtf8

octetsToBase64Binary

octetsToHexBinary

base64BinaryToOctets

hexBinaryToOctets

base64BinaryToString

stringToBase64Binary

hexBinaryToString

readBinaryResource

stringToHexBinary

validCharacter

namespaceNode

unparsedEntities

inSummerTime

adjustToCivilTime

currentModeName

isDefaulted