### Saxon.Api

- BinaryResource
- CatalogCollection
- DirectoryCollection
- DocumentBuilder
- DomDestination
- DynamicContext
- DynamicError
- EmptyEnumerator<T>
- ErrorReporter
- ErrorReporterToStaticError
- ErrorReporterWrapper
- ExtensionFunction
- ExtensionFunctionCall
- ExtensionFunctionDefinition
- Feature<T>
- FeatureKeys
- HostLanguage
- ICollectionFinder
- IErrorReporter
- IInvalidityHandler
- IMessageListener
- IMessageListener2
- InvalidityHandlerWrapper
- IPredicate<in XdmItem>
- IQueryResolver
- IResource
- IResourceCollection
- IResourceFactory
- IResultDocumentHandler
- IXmlLocation
- JarCollection
- NamespaceConstant
- NullDestination
- Predicate<T>
- Predicates
- Processor
- QName
- RawDestination
- RecoveryPolicy
- Resource
- ResourceCollection
- SchemaManager
- SchemaResolver
- SchemaValidationMode
- SchemaValidator
- Serializer
- StandardCollectionFinder
- StandardLogger
- StaticContext
- StaticError
- Step<TInput, TResult>
- Steps
- TextWriterDestination
- TreeModel
- URIQueryParameters
- ValidationFailure
- WhitespacePolicy
- XdmAnyArrayType
- XdmAnyFunctionType
- XdmAnyItemType
- XdmAnyMapType
- XdmAnyNodeType
- XdmArray
- XdmAtomicType
- XdmAtomicValue
- XdmAxis
- XdmDestination
  - - TreeProtector
- XdmEmptySequence
- XdmExternalObjectValue
- XdmFunctionItem
- XdmItem
- XdmItemType
- XdmMap
- XdmNode
- XdmNodeKind
- XdmSequenceType
- XdmValue
- XmlDestination
- XmlProcessingError
- XmlResource
- XPathCompiler
- XPathExecutable
- XPathSelector
- XQueryCompiler
- XQueryEvaluator
- XQueryExecutable
- Xslt30Transformer
- XsltCompiler
- XsltExecutable
  - - ParameterDetails
- XsltPackage
- XsltTransformer

### Saxon.Api

# Class XPathCompiler

public class XPathCompiler

An `XPathCompiler` object allows XPath queries to be compiled. The compiler holds information that represents the static context for the expression.

To construct an `XPathCompiler`, use the factory method `NewXPathCompiler` on the Processor object.

An `XPathCompiler` may be used repeatedly to compile multiple queries. Any changes made to the `XPathCompiler` (that is, to the static context) do not affect queries that have already been compiled. An `XPathCompiler` may be used concurrently in multiple threads, but it should not then be modified once initialized.

The `XPathCompiler` has the ability to maintain a cache of compiled expressions. This is active only if enabled by setting the `Caching` property. If caching is enabled, then the compiler will recognize an attempt to compile the same expression twice, and will avoid the cost of recompiling it. The cache is emptied by any method that changes the static context for subsequent expressions, for example, by setting the `BaseUri` property. Unless the cache is emptied, it grows indefinitely: compiled expressions are never discarded.

### Property Summary
bool | AllowUndeclaredVariables This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling `DeclareVariable`. The property is false by default (that is, variables must be declared).
bool | BackwardsCompatible XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).
string | BaseUri The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the `doc()` function.
bool | Caching This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the `XPathCompiler` that would affect the validity of cached expressions. Caching is disabled by default.
XdmItemType | ContextItemType The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.
bool | FastCompliation Request fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.
net.sf.saxon.s9api.XPathCompiler | Implementation Escape hatch to the `net.sf.saxon.s9api.XPathCompiler` object in the underlying Java implementation
Processor | Processor Get the `Processor` from which this `XPathCompiler` was constructed
bool | SchemaAware Say whether XPath expressions compiled using this `XPathCompiler` are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.
IErrorReporter | WarningHandler Set the error reporter to be used for reporting static warnings during compilation. By default, the ErrorReporter associated with the Saxon Configuration is used. Note that fatal static errors are always reported in the form of an exception thrown by the XPathCompiler.Compile(String) method, so this method only controls the handling of warnings
string | XPathLanguageVersion This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", and "3.1". The default is "3.1".

### Method Summary
void | AddXsltFunctionLibrary(XsltPackage libraryPackage) Make available a set of functions defined in an XSLT 3.0 package. All functions defined with `visibility="public"` (or exposed as public using `xsl:expose` become part of the static context for an XPath expression created using this `XPathCompiler`. The functions are added to the search path after all existing functions, including functions added using a previous call on this method. Note that if the library package includes functions that reference stylesheet parameters (or global variables that depend on the context item), then there is no way of supplying values for such parameters; calling such functions will cause a run-time error.
XPathExecutable | Compile(string source) Compile an expression supplied as a `String`.
void | DeclareDefaultCollation(string uri) Declare the default collation
void | DeclareNamespace(string prefix, string uri) Declare a namespace for use by the XPath expression.
void | DeclareVariable(QName name) Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the `AllowUndeclaredVariables` property has been set to true.
XdmValue | Evaluate(string expression, XdmItem contextItem) Compile and execute an expression supplied as a `String`, with a given context item.
XdmItem | EvaluateSingle(string expression, XdmItem contextItem) Compile and execute an expression supplied as a `String`, with a given context item, where the expression is expected to return a single item as its result.
string | GetNamespaceURI(string lexicalName, bool useDefault) Get the namespace URI part of a QName provided in lexical form (`prefix:localname`)
void | ImportSchemaNamespace(string uri) Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.
void | SetDecimalFormatProperty(QName format, string property, string value) Sets a property of a selected decimal format, for use by the `format-number()` function.

## Property Detail

### AllowUndeclaredVariables

public bool AllowUndeclaredVariables {get; set; }

This property indicates whether the XPath expression may contain references to variables that have not been explicitly declared by calling `DeclareVariable`. The property is false by default (that is, variables must be declared).

If undeclared variables are permitted, then it is possible to determine after compiling the expression which variables it refers to by calling the method `EnumerateExternalVariables` on the `XPathExecutable` object.

### BackwardsCompatible

public bool BackwardsCompatible {get; set; }

XPath 1.0 Backwards Compatibility Mode (that is, XPath 1.0 compatibility mode). If true, backwards compatibility mode is set. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).

Setting XPath 1.0 compatibility mode does not prevent the use of constructs defined in a later XPath version; rather, it modifies the semantics of some constructs.

### BaseUri

public string BaseUri {get; set; }

The base URI of the expression, which forms part of the static context of the expression. This is used for resolving any relative URIs appearing within the expression, for example in the argument to the `doc()` function.

### Caching

public bool Caching {get; set; }

This property controls caching of compiled XPath expressions. If caching is enabled, then compiled expressions are saved in a cache and reused if the same expression is compiled again. The cache is cleared (invalidated) if any change is made to the properties of the `XPathCompiler` that would affect the validity of cached expressions. Caching is disabled by default.

### ContextItemType

public XdmItemType ContextItemType {get; set; }

The required context item type for the expression. This is used for optimizing the expression at compile time, and to check at run-time that the value supplied for the context item is the correct type.

### FastCompliation

public bool FastCompliation {get; set; }

Request fast compilation. Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the expression is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

Set to true to request fast compilation; set to false to revert to the optimization options defined in the Configuration.

### Implementation

public net.sf.saxon.s9api.XPathCompiler Implementation {get; }

Escape hatch to the `net.sf.saxon.s9api.XPathCompiler` object in the underlying Java implementation

### Processor

public Processor Processor {get; }

Get the `Processor` from which this `XPathCompiler` was constructed

### SchemaAware

public bool SchemaAware {get; set; }

Say whether XPath expressions compiled using this `XPathCompiler` are schema-aware. They will automatically be schema-aware if the method XPathCompiler.ImportSchemaNamespace(String) is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.

### WarningHandler

public IErrorReporter WarningHandler {set; }

Set the error reporter to be used for reporting static warnings during compilation. By default, the ErrorReporter associated with the Saxon Configuration is used. Note that fatal static errors are always reported in the form of an exception thrown by the XPathCompiler.Compile(String) method, so this method only controls the handling of warnings

The property IErrorReporter to which warnings will be notified

### XPathLanguageVersion

public string XPathLanguageVersion {get; set; }

This property indicates which version of XPath language syntax is accepted. The accepted values are "2.0", "3.0", and "3.1". The default is "3.1".

Requesting a value other than 3.1 restricts the XPath grammar to constructs defined in the appropriate version, and uses the appropriate subsets of the functions in the standard function library. However, the semantics of remaining constructs will generally follow the XPath 3.1 rules. For example, there is a rule in XPath 2.0 that casting to `xs:QName` is only permitted if the operand is a string literal, but this is not enforced when this property is set to "2.0".

There is no support for XPath 1.0.

## Method Detail

### AddXsltFunctionLibrary

public void AddXsltFunctionLibrary(XsltPackage libraryPackage)

Make available a set of functions defined in an XSLT 3.0 package. All functions defined with `visibility="public"` (or exposed as public using `xsl:expose` become part of the static context for an XPath expression created using this `XPathCompiler`. The functions are added to the search path after all existing functions, including functions added using a previous call on this method.

Note that if the library package includes functions that reference stylesheet parameters (or global variables that depend on the context item), then there is no way of supplying values for such parameters; calling such functions will cause a run-time error.

Parameters:

`libraryPackage` - the XSLT compiled library package whose functions are to be made available

### Compile

public XPathExecutable Compile(string source)
throws
StaticError

Compile an expression supplied as a `String`.

Parameters:

`source` - A string containing the source text of the XPath expression

Returns:

An `XPathExecutable` which represents the compiled XPath expression object. The `XPathExecutable` may be run as many times as required, in the same or a different thread. The `XPathExecutable` is not affected by any changes made to the `XPathCompiler` once it has been compiled.

Throws:

StaticError - Throws a `Saxon.Api.StaticError` if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.

### DeclareDefaultCollation

public void DeclareDefaultCollation(string uri)

Declare the default collation

Parameters:

`uri` - the absolute URI of the default collation. This URI must identify a known collation; either one that has been explicitly declared, or one that is recognized implicitly, such as a UCA collation

### DeclareNamespace

public void DeclareNamespace(string prefix,
string uri)

Declare a namespace for use by the XPath expression.

Parameters:

`prefix` - The namespace prefix to be declared. Use a zero-length string to declare the default namespace (that is, the default namespace for elements and types).
`uri` - The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace.

### DeclareVariable

public void DeclareVariable(QName name)

Declare a variable for use by the XPath expression. If the expression refers to any variables, then they must be declared here, unless the `AllowUndeclaredVariables` property has been set to true.

Parameters:

`name` - The name of the variable, as a `QName`

### Evaluate

public XdmValue Evaluate(string expression,
XdmItem contextItem)
throws
StaticError,
DynamicError

Compile and execute an expression supplied as a `String`, with a given context item.

Parameters:

`expression` - A string containing the source text of the XPath expression
`contextItem` - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

An `XdmValue` which is the result of evaluating the XPath expression.

Throws:

StaticError - Throws a `Saxon.Api.StaticError` if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
DynamicError - Throws a `Saxon.Api.DynamicError` if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.

### EvaluateSingle

public XdmItem EvaluateSingle(string expression,
XdmItem contextItem)
throws
StaticError,
DynamicError

Compile and execute an expression supplied as a `String`, with a given context item, where the expression is expected to return a single item as its result.

Parameters:

`expression` - A string containing the source text of the XPath expression
`contextItem` - The context item to be used for evaluation of the XPath expression. May be null, in which case the expression is evaluated without any context item.

Returns:

If the XPath expression returns a singleton, then the the `XdmItem` which is the result of evaluating the XPath expression. If the expression returns an empty sequence, then null. If the expression returns a sequence containing more than one item, then the first item in the result.

Throws:

StaticError - Throws a `Saxon.Api.StaticError` if there is any static error in the XPath expression. This includes both syntax errors, semantic errors such as references to undeclared functions or variables, and statically-detected type errors.
DynamicError - Throws a `Saxon.Api.DynamicError` if there is any dynamic error during evaluation of the XPath expression. This includes, for example, referring to the context item if no context item was supplied.

### GetNamespaceURI

public string GetNamespaceURI(string lexicalName,
bool useDefault)

Get the namespace URI part of a QName provided in lexical form (`prefix:localname`)

Parameters:

`lexicalName` - The lexical QName. This may either be a plain `NCName` (a local name with no prefix or colon) or a lexical name using a prefix that is bound to a namespace.
`useDefault` - Set to true if the default namespace for elements and types is to be used in the case where there is no prefix. If false, no prefix means no namespace.

Returns:

The namespace URI associated with the prefix (or absence thereof) in the supplied lexical QName. The "null namespace" is represented by a zero length string. The method returns null if there is no known binding for the prefix used in the lexical QName.

### ImportSchemaNamespace

public void ImportSchemaNamespace(string uri)

Import schema definitions for a specified namespace. That is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.

This method will not cause the schema to be loaded. That must be done separately, using the `SchemaManager`. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.

This method does not bind a prefix to the namespace. That must be done separately, using the `DeclareNamespace` method.

Parameters:

`uri` - The namespace URI whose declarations and type definitions are to be made available for use within the XPath expression.

### SetDecimalFormatProperty

public void SetDecimalFormatProperty(QName format,
string property,
string value)

Sets a property of a selected decimal format, for use by the `format-number()` function.

This method checks that the value is valid for the particular property, but it does not check that all the values for the decimal format are consistent (for example, that the decimal separator and grouping separator have different values). This consistency check is performed only when the decimal format is used.

Parameters:

`format` - The name of the decimal format whose property is to be set. It is not possible to set the properties for the default (unnamed) decimal format. This correponds to a name used in the third argument of `format-number()`.
`property` - The name of the property to set: one of "decimal-separator", "grouping-separator", "infinity", "NaN", "minus-sign", "percent", "per-mille", "zero-digit", "digit", or "pattern-separator".
`value` - The new value for the property.