The Evaluate method allows the execution of XPath 2.0+ and XQuery 1.0+ expressions against the data contained within the XML object. This is a lazy execution method that compiles and evaluates the provided expression in a single step, returning the result as a string. For more complex scenarios or repeated evaluations, consider using the Compile and Evaluate functions in the XPath module.

The Filter method provides a mechanism for reducing large XML documents to a specific subtree, permanently removing all content that exists outside the targeted element and its children. This operation is particularly valuable for performance optimisation when working with large documents where only a specific section is relevant.

The filtering process locates the first element matched by the supplied XPath/XQuery expression. The XML object is then replaced by a new root-level structure containing that tag and its descendants. Sibling tags, parent elements and unrelated branches are discarded.

The GetAttrib method provides efficient access to individual attribute values within XML elements. Given a tag identifier and attribute name, the method performs a case-insensitive search through the element's attribute collection and returns the corresponding value.

When a specific attribute name is provided, the method searches through all attributes of the target tag. The search is case-insensitive to accommodate XML documents with varying capitalisation conventions.

When the attribute name is empty, the method returns the tag name itself, providing convenient access to element names without requiring separate API calls.

For applications requiring frequent attribute access or high-performance scenarios, C++ developers should consider direct access to the XMLAttrib structure array. This bypasses the method call overhead and provides immediate access to all attributes simultaneously.

The method performs a linear search through the attribute collection, so performance scales with the number of attributes per element. For elements with many attributes, caching frequently accessed values may improve performance.

The GetContent method extracts only the immediate content-node children of the specified element. Text contained inside nested elements is not included.

Consider the following XML structure:

<body>
  Hello
  <bold>emphasis</bold>
  world!
</body>

The GetContent method would extract Hello world! and deliberately exclude emphasis since it is contained within the nested <bold> element.

For scenarios requiring serialised XML rather than immediate text content, use Serialise(). To inspect nested text content, traverse the child XTag hierarchy directly.

It is recommended that C++ programs bypass this method and access the XMLAttrib structure directly.

This method returns the expanded value associated with a general entity parsed from the document's DOCTYPE declaration. Entity names are case-sensitive and must match exactly as declared.

This method retrieves the original namespace URI string for a given namespace UID.

Returns the system or public identifier captured for a notation declaration inside the document type definition. If both public and system identifiers were provided they are returned as a single string separated by a single space.

This method will return the XTag structure for a given tag Index. The Index is checked to ensure it is valid prior to retrieval, and an ERR::NotFound error will be returned if it is invalid.

The InsertContent method will insert content strings into any position within the XML tree. A content string must be provided in the Content parameter and the target insertion point is specified in the Index parameter. An insertion point relative to the target index must be specified in the Where parameter. The new tags can be inserted as a child of the target by using a Where value of XMI::CHILD. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

To modify existing content, call SetAttrib() instead.

The InsertXML() method is used to translate and insert a new set of XML tags into any position within the XML tree. A standard XML statement must be provided in the XML parameter and the target insertion point is specified in the Index parameter. An insertion point relative to the target index must be specified in the Where parameter. The new tags can be inserted as a child of the target by using a Where value of XMI::CHILD. Use XMI::CHILD_END to insert at the end of the child list. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

The InsertXPath method is used to translate and insert a new set of XML tags into any position within the XML tree. A standard XML statement must be provided in the XML parameter and the target insertion point is referenced as a valid XPath location string. An insertion point relative to the XPath target must be specified in the Where parameter. The new tags can be inserted as a child of the target by using a Where value of XMI::CHILD or XMI::CHILD_END. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

This method parses an XML Schema document and attaches its schema context to the current XML object. Once loaded, schema metadata is available for validation and XQuery evaluation routines that utilise schema-aware behaviour.

This method is used to move XML tags within the XML tree structure. It supports the movement of single and groups of tags from one index to another. The client must supply the index of the tag that will be moved and the index of the target tag. All child tags of the source will be included in the move.

An insertion point relative to the target index must be specified in the Where parameter. The source tag can be inserted as a child of the destination by using XMI::CHILD or XMI::CHILD_END. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

This method registers a namespace URI and returns a UID that can be used to identify the namespace efficiently throughout the XML document.

The RemoveTag method is used to remove one or more tags from an XML structure. Child tags will automatically be discarded as a consequence of using this method, in order to maintain a valid XML structure.

This method can delete multiple sibling tags when the Total parameter is greater than 1. Each selected tag and its children are removed. The requested range should stay within the available sibling sequence.

Note: Removing tags will destabilise all cached address pointers that have been acquired from the XML object.

The RemoveXPath method is used to remove one or more tags from an XML structure. Child tags will automatically be discarded as a consequence of using this method, in order to maintain a valid XML structure.

Individual tag attributes can also be removed if an attribute is referenced at the end of the XPath.

The removal routine is repeated until no further match is found or the Limit is reached. No-match completion is reported as ERR::Okay.

This method is volatile and will destabilise any cached address pointers that have been acquired from the XML object.

This method resolves a namespace prefix to its corresponding namespace URI hash by examining namespace declarations within the specified tag's hierarchical scope. The resolution process:

1. Walks up the tag hierarchy from the specified tag to the root.
2. Examines xmlns:prefix and xmlns attributes in each tag to find the declaration.
3. Returns the UID of the first matching namespace URI found.

This approach correctly handles nested namespace scopes and prefix redefinitions.

The Search method provides the primary mechanism for locating XML elements within the document structure using XPath and XQuery expressions. The method supports both single-result queries and comprehensive tree traversal with callback-based processing for complex operations.

When no callback function is provided, Search returns the first matching element and terminates the search immediately. This is optimal for simple queries where only the first occurrence is required.

When a callback function is specified, Search calls it for each matching element until the query completes, the callback returns an error, or the callback returns ERR::Terminate.

The C++ prototype for Callback is ERR Function(*XML, int TagID, CSTRING Attrib, APTR Meta).

The callback should return ERR::Okay to continue processing, or ERR::Terminate to halt the search immediately. Other callback errors are returned to the caller.

Note: If an error occurs, check the ErrorMsg field for a custom error message containing further details.

The Serialise() method will serialise all or part of the XML data tree to a string.

The string will be copied into the caller-provided Result parameter.

This method updates existing XML tag attributes, creates new attributes and clears content.

The data for the attribute is defined in the Name and Value parameters. Use an empty string if no data is to be associated with the attribute. Set Attrib to XMS::REMOVE to remove an attribute, or to clear element content if Name is empty.

NOTE: The attribute at position 0 declares the name of the tag and should not normally be accompanied with a value declaration. However, if the tag represents content within its parent, then the Name must be left empty and the Value string will determine the content.

This method assigns a namespace to an XML tag using the namespace's UID.

The Sort method is used to sort a single branch of XML tags in ascending or descending order. An XPath is required that refers to the tag containing each item that will be sorted. To sort the root level, use an empty XPath.

The Sort parameter is used to specify a list of sorting instructions. The format for the Sort string is Tag:Attrib,Tag:Attrib,.... The Tag indicates the tag name that should be identified for sorting each node, and child tags are supported for this purpose. Wildcard filtering is allowed and a Tag value of * will match every tag at the requested XPath level. The optional Attrib value names the attribute containing the sort string. To sort on content, do not define an Attrib value (use the format Tag,Tag,...).

This method performs structural and simple type validation of the document using the loaded XML Schema. It returns ERR::Okay when the document conforms to the schema. Validation failures return an error and populate ErrorMsg with the reason where available.