Xml Rust Reference Documentation

Xml

Current Version: 11.6.1

Chilkat.Xml

Load, navigate, search, edit, transform, and save in-memory XML trees.

Chilkat.Xml is the primary Chilkat class for in-memory XML tree manipulation. It supports loading and saving XML, navigating between elements, reading and writing text content, managing attributes, working with namespaces, adding and removing subtrees, searching by tag, content, or attribute, sorting child records, scrubbing XML, handling CDATA and XML declarations, storing binary data as Base64, and optionally compressing or encrypting element content.

Load and save XML

Load XML from strings, files, byte data, or other Chilkat objects, then save or emit formatted XML when processing is complete.

Navigate XML trees

Move through parent, child, sibling, and selected elements while working directly with the XML document structure.

Edit elements and attributes

Add, update, remove, or rename elements; set text content; and read, add, modify, or delete attributes.

Search and select

Locate elements by tag name, content, path, attribute value, or custom search patterns.

Namespaces and structure

Work with namespace-aware XML, declarations, CDATA, child ordering, sorting, and subtree insertion or removal.

Binary and protected content

Store binary data as Base64 and optionally compress or encrypt element content when XML carries encoded payloads.

Important usage distinction: Some methods return a new Xml object reference for the selected element, while methods ending in 2 update the caller's internal reference to point to a different element. This distinction is central when navigating and editing XML trees because it determines whether the current object stays where it is or moves to another element.
Common pattern: Load or create the XML document, navigate to the element of interest, read or modify content and attributes, add or remove child elements as needed, then save the updated XML. Use Chilkat.Xml for tree-oriented XML manipulation, and use Chilkat.XmlDSig, Chilkat.XmlDSigGen, or related classes when the task is XML digital signing or signature verification.

For an extended overview, see Xml Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Xml;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let xml = Xml::new();
// ... the native object is freed when `xml` goes out of scope.
pub fn new() -> Xml

Creates the underlying native Chilkat object (Xml also implements Default). Every method takes &self, so the object never needs to be declared mut. A Xml is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Xml

The native object is freed when the Xml is dropped — when it goes out of scope, or explicitly with drop(xml). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Xml>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match xml.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

Cdata
// read/write
pub fn cdata(&self) -> bool
pub fn set_cdata(&self, value: bool)

Controls how this element's text content is emitted. When set to true, the element content is written inside a CDATA section instead of being emitted as ordinary character data with XML escaping.

CDATA and escaping: CDATA is useful when text contains many characters such as < or &. It does not change the logical text value of the element; it only changes how that text is represented in the serialized XML.

More Information and Examples
Using CDATA in XML
top
Content
// read/write
pub fn content(&self) -> String
pub fn set_content(&self, value: &str)

Gets or sets the text content stored directly on this XML element. Child elements are not included in this value.

For example, both of the following elements have This is the content as their Content:

<tag1>This is the content</tag1>

<tag2><child1>abc</child1><child2>abc</child2>This is the content</tag2>
Content vs. children: Chilkat stores an element's direct text content separately from its child elements. Use the child-navigation methods when you need the nested elements themselves.

More Information and Examples
Content vs. Children: A common misconception explained.Setting XML Tag and Content
top
ContentInt
// read/write
pub fn content_int(&self) -> i32
pub fn set_content_int(&self, value: i32)

Gets or sets this element's content as a 32-bit integer. Setting the property converts the integer to its decimal text representation; getting the property interprets the element's text content as an integer.

Numeric content: Use Content when the value may exceed the range of a 32-bit integer or when the exact lexical representation must be preserved.

top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
DocType
// read/write
pub fn doc_type(&self) -> String
pub fn set_doc_type(&self, value: &str)

Gets or sets the document type declaration associated with the XML document.

The value represents the document-level DOCTYPE declaration, for example <!DOCTYPE note SYSTEM "note.dtd">.

Document-level setting: Although this property may be accessed from any element reference in the tree, the DOCTYPE belongs to the XML document as a whole rather than to an individual element.

More Information and Examples
Setting the XML DOCTYPE
top
EmitBom
// read/write
pub fn emit_bom(&self) -> bool
pub fn set_emit_bom(&self, value: bool)
Introduced in version 9.5.0.44

Controls whether a byte order mark (BOM, also called a preamble) is written when XML is saved to a file. The default is false.

This setting is relevant to encodings for which a BOM can be emitted, such as UTF-8 and UTF-16. It does not affect XML returned as a language string by methods such as GetXml.

top
EmitCompact
// read/write
pub fn emit_compact(&self) -> bool
pub fn set_emit_compact(&self, value: bool)
Introduced in version 9.5.0.64

Controls whether XML emitted by GetXml and GetXmlSb is compact. When true, unnecessary formatting whitespace and line breaks are omitted. The default is false for backward compatibility.

Formatting only: Compact output changes presentation, not the XML tree or its element content.

More Information and Examples
XML EmitCompact
top
EmitXmlDecl
// read/write
pub fn emit_xml_decl(&self) -> bool
pub fn set_emit_xml_decl(&self, value: bool)

Controls whether the XML declaration is included when XML is emitted. The default is true. When set to false, output methods such as GetXml and SaveXml omit the declaration.

An XML declaration is the leading construct such as <?xml version="1.0" encoding="utf-8"?>.

top
Encoding
// read/write
pub fn encoding(&self) -> String
pub fn set_encoding(&self, value: &str)

Gets or sets the encoding value used in the XML declaration. The default is utf-8. This is a document-level setting and may be accessed from any element in the tree.

When XML is loaded, Chilkat sets this property from the encoding declared by the input XML when one is present. If no encoding is declared, the property is reset to utf-8.

Important: Changing Encoding changes the declared/output encoding used when XML is serialized; it does not reinterpret or transcode the already-stored Unicode text inside the in-memory tree.

top
I
// read/write
pub fn i(&self) -> i32
pub fn set_i(&self, value: i32)
Introduced in version 9.5.0.64

Provides a substitution value for [i] in Chilkat tag paths and ChilkatPath expressions. When a path contains [i], the current value of this property is substituted for I.

Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.

More Information and Examples
Demonstrate the XML "I" PropertyDemonstrate the XML I, J, and K Properties
top
IsBase64
// read-only
pub fn is_base64(&self) -> bool
Introduced in version 9.5.0.76

Returns true if this element's content consists only of characters allowed in standard Base64 text, with whitespace ignored. Standard Base64 uses A-Z, a-z, 0-9, +, /, and optional trailing = padding.

Syntax check, not semantic validation: A value can contain only Base64 characters and still not represent the data your application expects. This property is useful as a quick content-format test.

top
J
// read/write
pub fn j(&self) -> i32
pub fn set_j(&self, value: i32)
Introduced in version 9.5.0.64

Provides a substitution value for [j] in Chilkat tag paths and ChilkatPath expressions. When a path contains [j], the current value of this property is substituted for J.

Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.

More Information and Examples
Demonstrate the XML I, J, and K Properties
top
K
// read/write
pub fn k(&self) -> i32
pub fn set_k(&self, value: i32)
Introduced in version 9.5.0.64

Provides a substitution value for [k] in Chilkat tag paths and ChilkatPath expressions. When a path contains [k], the current value of this property is substituted for K.

Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
NumAttributes
// read-only
pub fn num_attributes(&self) -> i32

Returns the number of attributes on this element.

For example, <tag attr1="value1" attr2="value2">...</tag> has two attributes. Attribute indexes used by methods such as GetAttributeName and GetAttributeValue are zero-based.

More Information and Examples
Methods for Getting Attributes
top
NumChildren
// read-only
pub fn num_children(&self) -> i32

Returns the number of direct child elements of this element. Descendants below those children are not included in the count.

Direct children only: Use traversal or search methods when you need to inspect the entire subtree rather than only the immediate children.

top
SortCaseInsensitive
// read/write
pub fn sort_case_insensitive(&self) -> bool
pub fn set_sort_case_insensitive(&self, value: bool)

Controls case sensitivity for the XML sorting methods. Set to true for case-insensitive string comparisons or false for case-sensitive comparisons.

top
Standalone
// read/write
pub fn standalone(&self) -> bool
pub fn set_standalone(&self, value: bool)

Controls the standalone pseudo-attribute in the XML declaration. This is a document-level setting and may be accessed from any element in the tree.

Setting this property to true causes the declaration to include standalone="yes".

XML declaration: The standalone declaration concerns whether the document relies on external markup declarations. It is metadata in the XML declaration; it does not by itself validate or alter the document.

top
Strict
// read/write
pub fn strict(&self) -> bool
pub fn set_strict(&self, value: bool)
Introduced in version 11.6.0

When Strict is true, the XML loading methods first check that the input is well-formed XML. If it is not, the load fails and the contents of this Xml object are left unchanged. The default is false.

This applies to LoadXml, LoadXml2, LoadSb, LoadBd, LoadXmlFile and LoadXmlFile2.

Chilkat's XML parser is deliberately tolerant. By default it can accept input that is not well-formed, succeed, and leave a partially populated tree. That is convenient when the goal is a best-effort parse of imperfect input, but it is the wrong behavior when a silently dropped element or attribute changes what the application does.

Set Strict to true for XML carrying configuration, credentials, signed content, or security parameters, where an element that quietly failed to load would be acted on as though it had never been present.

The check is for XML 1.0 well-formedness only. It is not a validating parse: no DTD or schema is read, and the document is not checked against one. Markup declarations inside an internal DTD subset are skipped rather than parsed.

Note: The default is false so that existing applications are unaffected. When a strict load is rejected, this Xml object keeps whatever it held before the call, so a failed reload never leaves the object empty.

top
Tag
// read/write
pub fn tag(&self) -> String
pub fn set_tag(&self, value: &str)

Gets or sets the element name for this element, including any namespace prefix. For example, the tag for <soapenv:Body> is soapenv:Body.

Use TagNsPrefix and TagUnprefixed when the prefix and local portion are needed separately.

More Information and Examples
Setting XML Tag and Content
top
TagNsPrefix
// read/write
pub fn tag_ns_prefix(&self) -> String
pub fn set_tag_ns_prefix(&self, value: &str)
Introduced in version 9.5.0.77

Gets or sets the namespace prefix portion of this element's tag. For soapenv:Envelope, the namespace prefix is soapenv.

Prefix vs. namespace URI: This property deals with the lexical prefix in the tag name. A prefix is not itself the namespace URI; namespace bindings are expressed through xmlns attributes in the XML.

More Information and Examples
Handling Namespaces in XML Tags
top
TagPath
// read-only
pub fn tag_path(&self) -> String
Introduced in version 9.5.0.77

Returns the Chilkat tag path needed to reach this element from the document root. If this object currently references the root element, the returned path is the empty string.

Not XPath: A Chilkat tag path is Chilkat's own navigation syntax, typically using | between element names. It is not an XPath expression.

More Information and Examples
Xml TagPath Property Explained
top
TagUnprefixed
// read/write
pub fn tag_unprefixed(&self) -> String
pub fn set_tag_unprefixed(&self, value: &str)
Introduced in version 9.5.0.77

Gets or sets the unprefixed portion of this element's tag. For soapenv:Envelope, the unprefixed tag is Envelope.

Use TagNsPrefix to access the prefix separately.

More Information and Examples
Handling Namespaces in XML Tags
top
TreeId
// read-only
pub fn tree_id(&self) -> i32

Returns the identifier of the XML tree to which this element belongs. Elements in the same XML document have the same TreeId.

Useful for element references: Multiple Xml objects can reference different elements in the same underlying tree. Comparing TreeId values is a convenient way to determine whether two element references belong to that same tree.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.90

Provides a catch-all string for uncommon XML behaviors. The default is the empty string, which is appropriate for normal use.

Leave this property empty unless Chilkat documentation or support identifies a specific option needed for a specialized interoperability case.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

AccumulateTagContent
pub fn accumulate_tag_content(&self, tag: &str, skip_tags: &str) -> Result<String>

Traverses the subtree rooted at the calling element and concatenates the text content of all elements whose tag equals tag.

skipTags is a vertical-bar-delimited list of tag names whose entire subtrees are excluded from the accumulation. For example, script|style skips elements rooted at either of those tags.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML Accumulate Tag Content
top
AddAttribute
pub fn add_attribute(&self, name: &str, value: &str) -> Result<()>

Adds an attribute named name with the specified string value to the calling element.

Returns true on success and false on failure.

When an attribute may already exist: Use AddOrUpdateAttribute or UpdateAttribute when the desired behavior is to update an existing attribute value instead of requiring a new attribute.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
AddAttribute - Insert New Attribute in XML Node
top
AddAttributeInt
pub fn add_attribute_int(&self, name: &str, value: i32) -> Result<()>

Adds an attribute named name whose value is the decimal representation of value.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
AddChildTree
pub fn add_child_tree(&self, tree: &Xml) -> Result<()>

Adds the entire XML subtree referenced by tree as a new direct child of the calling element.

If tree already belongs to another XML document, the subtree is transferred to the destination tree rather than copied as an unrelated duplicate.

Tree ownership: After moving a subtree between documents, its elements belong to the destination tree. TreeId can be used to determine which tree an element reference belongs to.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
XML Add Child Tree
top
AddOrUpdateAttribute
pub fn add_or_update_attribute(&self, name: &str, value: &str)

Sets the string value of an attribute on the calling element. If an attribute named name already exists, its value is replaced; otherwise the attribute is added.

More Information and Examples
Update an XML Attribute
top
AddOrUpdateAttributeI
pub fn add_or_update_attribute_i(&self, name: &str, value: i32)

Sets an integer-valued attribute on the calling element. If an attribute named name already exists, its value is replaced with the decimal representation of value; otherwise the attribute is added.

top
AddStyleSheet
pub fn add_style_sheet(&self, style_sheet: &str)

Adds an XML stylesheet processing instruction to the document. Pass the complete processing-instruction text, for example: 

<?xml-stylesheet href="mystyle.css" title="Compact" type="text/css"?>
Processing instruction: An XML stylesheet declaration associates stylesheet metadata with the XML document; it does not apply or execute the stylesheet.

top
AddToAttribute
pub fn add_to_attribute(&self, name: &str, amount: i32)

Treats the named attribute value as an integer, adds amount, and stores the resulting integer back in the attribute.

If the attribute does not yet exist, this method behaves like AddOrUpdateAttributeI and creates it with amount as the value.

More Information and Examples
Update an XML Attribute
top
AddToChildContent
pub fn add_to_child_content(&self, tag: &str, amount: i32)

Finds the child identified by tag, interprets its content as an integer, adds amount, and stores the resulting integer as the child's new content.

top
AddToContent
pub fn add_to_content(&self, amount: i32)

Interprets this element's content as an integer, adds amount, and stores the resulting integer as the new content.

top
AppendToContent
pub fn append_to_content(&self, str: &str) -> Result<()>

Appends str to the existing text content of the calling element without replacing its child elements.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
ChildContentMatches
pub fn child_content_matches(&self, tag_path: &str, pattern: &str, case_sensitive: bool) -> bool

Returns true if the child identified by tagPath has content matching pattern; otherwise returns false. caseSensitive controls whether letter case is significant.

The pattern may contain * wildcards, where each asterisk matches zero or more characters.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

top
ChilkatPath
pub fn chilkat_path(&self, path_cmd: &str) -> Result<String>

Evaluates a Chilkat-specific path command that can navigate from the current element, return element content or an attribute value, or move the caller's internal element reference.

This syntax is not XPath. Commands are separated by vertical bars and the expression ends with a return command:

command|command|command|...|returnCommand

Navigation commands include:

  • TagName - first direct child having that tag.
  • TagName[n] - the indexed direct child having that tag.
  • .. - parent.
  • ++ / -- - next / previous sibling.
  • TagName{Content} - first direct child with that tag and exact content.
  • /T/TagName - traverse the subtree and find the first element with that tag.
  • /C/TagName,ContentPattern - traverse for a tag whose content matches a wildcard pattern.
  • /C/ContentPattern - traverse for any tag whose content matches a wildcard pattern.
  • /A/TagName,AttrName,AttrValuePattern - traverse for a tag having a matching attribute value.

The final return command is:

  • * - return the current element's content.
  • (AttrName) - return an attribute value.
  • $ - move this Xml object to the selected element and return an empty string.
Index substitution: The I, J, and K properties can be used with [i], [j], and [k] in path expressions.

Returns Err(chilkat::Error) on failure.

More Information and Examples
ChilkatPath Sample CodeGet XML Attribute Value by PathFind XML Element where Attribute = Value
top
Clear
pub fn clear(&self)

Clears the calling element by removing all child elements, attributes, and text content, and resets its tag name to unnamed.

The element itself remains in the tree; this method clears its contents rather than removing the element from its parent.

top
ContentMatches
pub fn content_matches(&self, pattern: &str, case_sensitive: bool) -> bool

Returns true if this element's content matches pattern; otherwise returns false. caseSensitive controls whether letter case is significant.

The pattern may contain * wildcards, where each asterisk matches zero or more characters.

top
Copy
pub fn copy(&self, node: &Xml)

Copies the Tag, Content, and attributes from node to the calling element.

Not a subtree copy: This method does not copy the source element's children. Use a tree-oriented method such as AddChildTree or SwapTree when child structure is part of the operation.

top
CopyRef
pub fn copy_ref(&self, copy_from_node: &Xml)

Changes this Xml object so that it references the same underlying XML element as copyFromNode. The caller's previous element reference is discarded.

Reference operation: CopyRef does not copy XML data. After the call, both Xml objects refer to the same element, so edits through either reference affect the same tree element.

top
DecodeEntities
pub fn decode_entities(&self, str: &str) -> Result<String>

Decodes HTML character entities found in str and returns the decoded text. This is a utility operation; it does not modify the XML tree unless the returned string is assigned to an element.

For example, an HTML entity such as &amp; is decoded to &.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Decode HTML Entities found in XML
top
DecryptContent
pub fn decrypt_content(&self, password: &str) -> Result<()>

Decrypts element content previously produced by EncryptContent, using the same password, and restores the original plaintext content.

Returns true on success and false on failure.

Compatibility-oriented encryption: This method is paired specifically with EncryptContent. It is not a general XML Encryption (XML-Enc) implementation.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Encrypting and Decrypting Content
top
EncryptContent
pub fn encrypt_content(&self, password: &str) -> Result<()>

Encrypts the calling element's text content using Chilkat's password-based 128-bit AES-CBC format and replaces the plaintext content with Base64-encoded encrypted data.

Returns true on success and false on failure.

Scope: Only this element's content is encrypted. The tag, attributes, and child elements are not encrypted by this method. Use DecryptContent with the same password to restore the content.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Encrypting and Decrypting Content
top
ExtractChildByIndex
pub fn extract_child_by_index(&self, index: i32) -> Result<Xml>

Removes the direct child at zero-based index from the calling element and returns an Xml object for the detached child subtree.

Extract vs. remove: Unlike RemoveChildByIndex, extraction gives the caller a reference to the removed subtree so it can be retained, inspected, or attached elsewhere.

Returns Err(chilkat::Error) on failure.

top
ExtractChildByName
pub fn extract_child_by_name(&self, tag_path: &str, attr_name: &str, attr_value: &str) -> Result<Xml>

Finds, removes, and returns the first child selected by tagPath and the optional attribute criteria.

If attrName and attrValue are empty, the first child matching the tag/path is extracted. If attrName is provided, the child must have that attribute. If attrValue is also provided, the attribute value must match exactly.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Err(chilkat::Error) on failure.

More Information and Examples
ExtractChildByName using a Tag Path
top
FindChild
pub fn find_child(&self, tag_path: &str) -> Result<Xml>

Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Find Direct Child with Specific TagAccess SOAP Body XML
top
FindChild2
pub fn find_child2(&self, tag_path: &str) -> Result<()>

Moves the calling Xml object's internal reference to the child selected by tagPath. Returns true when the child is found and the move succeeds; otherwise returns false.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Find Direct Child with Specific TagBenefit of XML Methods Having Names Ending in "2"
top
FindNextRecord
pub fn find_next_record(&self, tag_path: &str, content_pattern: &str) -> Result<Xml>

Finds the next direct child record for which the descendant identified by tagPath has content matching contentPattern. This is intended for iterating record-like child elements.

The content pattern may contain * wildcards.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Demonstrate the XML FindNextRecord Method
top
FindOrAddNewChild
pub fn find_or_add_new_child(&self, tag_path: &str) -> Result<Xml>

Returns the child selected by tagPath if it already exists. If it does not exist, creates the required child path with empty content and returns the resulting child element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Use NewChild instead when duplicate children with the same tag are intentional.

Returns Err(chilkat::Error) on failure.

top
FirstChild
pub fn first_child(&self) -> Result<Xml>

Returns an Xml object referencing the first direct child of the calling element.

A common forward-iteration pattern is FirstChild followed by repeated calls to NextSibling.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSibling
top
FirstChild2
pub fn first_child2(&self) -> Result<()>

Moves the calling Xml object's internal reference to its first direct child. Returns true if a first child exists; otherwise returns false.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about XML methods ending in "2"Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSiblingBenefit of XML Methods Having Names Ending in "2"
top
GetAttributeName
pub fn get_attribute_name(&self, index: i32) -> Result<String>

Returns the name of the attribute at zero-based index. Use NumAttributes to determine the valid index range.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Methods for Getting Attributes
top
GetAttributeValue
pub fn get_attribute_value(&self, index: i32) -> Result<String>

Returns the value of the attribute at zero-based index. Use NumAttributes to determine the valid index range.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Methods for Getting Attributes
top
GetAttributeValueInt
pub fn get_attribute_value_int(&self, index: i32) -> i32

Returns the value of the attribute at zero-based index, interpreted as a 32-bit integer.

top
GetAttrValue
pub fn get_attr_value(&self, name: &str) -> Result<String>

Returns the value of the attribute named name on the calling element.

Use HasAttribute when the application must distinguish a missing attribute from an attribute whose value is empty.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Methods for Getting Attributes
top
GetAttrValueInt
pub fn get_attr_value_int(&self, name: &str) -> i32

Returns the value of the attribute named name interpreted as a 32-bit integer. Returns 0 if the attribute does not exist.

Ambiguous zero: Because a missing attribute and an attribute containing zero can both yield 0, call HasAttribute first when that distinction matters.

More Information and Examples
Methods for Getting Attributes
top
GetChild
pub fn get_child(&self, index: i32) -> Result<Xml>

Returns an Xml object referencing the direct child at zero-based index. The calling object remains positioned on its current element.

Use NumChildren to determine the valid child range.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Iterate over Direct Child Nodes by Index
top
GetChild2
pub fn get_child2(&self, index: i32) -> Result<()>

Moves the calling Xml object's internal reference to the direct child at zero-based index. Returns true on success and false if the child cannot be selected.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about XML methods ending in "2"Iterate over Direct Child Nodes by IndexBenefit of XML Methods Having Names Ending in "2"
top
GetChildAttrValue
pub fn get_child_attr_value(&self, tag_path: &str, attr_name: &str) -> Result<String>
Introduced in version 9.5.0.77

Returns the value of attribute attrName on the descendant element selected by tagPath.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Err(chilkat::Error) on failure.

top
GetChildBoolValue
pub fn get_child_bool_value(&self, tag_path: &str) -> bool

Returns the integer content of the child selected by tagPath as a Boolean value: content equal to 0 yields false; a non-zero integer yields true.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

More Information and Examples
Demonstrate the XML "I" Property
top
GetChildContent
pub fn get_child_content(&self, tag_path: &str) -> Result<String>

Returns the text content of the child selected by tagPath.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Content only: The returned value is the child element's direct Content; nested child elements are not serialized into this string.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Demonstrate the XML "I" Property
top
GetChildContentByIndex
pub fn get_child_content_by_index(&self, index: i32) -> Result<String>

Returns the text content of the direct child at zero-based index. Use NumChildren to determine the valid range.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Iterate over Direct Child Nodes by IndexSQS List Queues
top
GetChildContentSb
pub fn get_child_content_sb(&self, tag_path: &str, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.76

Finds the element selected by tagPath and appends that element's text content to sb.

The existing contents of the StringBuilder are preserved.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Extract PDF Invoice from FatturaElettronica XML
top
GetChildExact
pub fn get_child_exact(&self, tag: &str, content: &str) -> Result<Xml>

Returns the first direct child whose tag equals tag and whose text content exactly equals content.

The calling object remains positioned on its current element.

Returns Err(chilkat::Error) on failure.

top
GetChildIntValue
pub fn get_child_int_value(&self, tag_path: &str) -> i32

Returns the content of the child selected by tagPath, interpreted as a 32-bit integer.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Integer range: Use GetChildContent and parse the returned text separately when values may exceed the range of a 32-bit integer.

More Information and Examples
Demonstrate the XML "I" PropertyWorkaround for 32-bit Integer Limitations (+/- 2GB)
top
GetChildTag
pub fn get_child_tag(&self, index: i32) -> Result<String>

Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.

Returns Err(chilkat::Error) on failure.

top
GetChildTagByIndex
pub fn get_child_tag_by_index(&self, index: i32) -> Result<String>

Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Iterate over Direct Child Nodes by Index
top
GetChildWithAttr
pub fn get_child_with_attr(&self, tag_path: &str, attr_name: &str, attr_value: &str) -> Result<Xml>

Returns the child selected by tagPath that also has an attribute named attrName whose value exactly equals attrValue.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML GetChildWithAttr
top
GetChildWithContent
pub fn get_child_with_content(&self, content: &str) -> Result<Xml>

Returns the first direct child whose text content exactly equals content. The child tag may be any value.

Returns Err(chilkat::Error) on failure.

top
GetChildWithTag
pub fn get_child_with_tag(&self, tag_path: &str) -> Result<Xml>

Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

top
GetChildWithTag2
pub fn get_child_with_tag2(&self, tag_path: &str) -> Result<()>
Introduced in version 11.1.0

Moves the calling Xml object's internal reference to the child selected by tagPath. Returns true when the child is found and the move succeeds; otherwise returns false.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
GetNthChildWithTag
pub fn get_nth_child_with_tag(&self, tag: &str, n: i32) -> Result<Xml>

Returns the zero-based nth direct child whose tag exactly equals tag. Children with other tag names are ignored when counting matches.

Use NumChildrenHavingTag to determine how many matching children are available.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Iterate over Direct Children with a Specific TagParsing XML Children Having Identical Tags
top
GetNthChildWithTag2
pub fn get_nth_child_with_tag2(&self, tag: &str, n: i32) -> Result<()>

Moves the calling Xml object's internal reference to the zero-based nth direct child whose tag equals tag. Returns true on success and false when no such child exists.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Iterate over Direct Children with a Specific TagBenefit of XML Methods Having Names Ending in "2"
top
GetParent
pub fn get_parent(&self) -> Result<Xml>

Returns an Xml object referencing this element's parent. Returns no parent when the current element is the document root.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

top
GetParent2
pub fn get_parent2(&self) -> Result<()>

Moves the calling Xml object's internal reference to its parent. Returns true if a parent exists; otherwise returns false when already at the root.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about XML methods ending in "2"Benefit of XML Methods Having Names Ending in "2"
top
GetRoot
pub fn get_root(&self) -> Result<Xml>

Returns an Xml object referencing the root element of the XML tree that contains the current element. The calling object remains positioned on its current element.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

top
GetRoot2
pub fn get_root2(&self)

Moves the calling Xml object's internal reference to the root element of its XML tree.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

More Information and Examples
More information about XML methods ending in "2"Benefit of XML Methods Having Names Ending in "2"
top
GetSelf
pub fn get_self(&self) -> Result<Xml>

Returns a new Xml object that references the same underlying XML element as the calling object.

Shared element reference: This is not a deep copy. Both objects reference the same element, so changes made through either object are changes to the same XML tree.

Returns Err(chilkat::Error) on failure.

top
GetXml
pub fn get_xml(&self) -> Result<String>

Serializes the XML tree or subtree rooted at the current element and returns the XML text.

When called while positioned on the document root, the XML declaration is included if EmitXmlDecl is true. When called on a non-root element, only that subtree is emitted and the document declaration is not included.

EmitCompact, Encoding, Standalone, and related document/output properties affect serialization as applicable.

String vs. bytes: A language string is Unicode text. The Encoding declaration describes serialized XML encoding, while actual byte encoding matters when XML is written to a file or byte-oriented destination.

Returns Err(chilkat::Error) on failure.

top
GetXmlBd
pub fn get_xml_bd(&self, bd: &BinData) -> Result<()>
Introduced in version 9.5.0.77

Serializes the XML tree or subtree rooted at the current element and appends the encoded XML bytes to bd.

The existing contents of the BinData object are preserved. The XML output encoding is governed by the XML document's output settings, including Encoding.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
GetXmlSb
pub fn get_xml_sb(&self, sb: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.62

Serializes the XML tree or subtree rooted at the current element and appends the resulting XML text to sb.

The existing contents of sb are preserved. Output properties such as EmitCompact and EmitXmlDecl apply as appropriate.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
HasAttribute
pub fn has_attribute(&self, name: &str) -> bool

Returns true if the calling element has an attribute named name; otherwise returns false.

top
HasAttrWithValue
pub fn has_attr_with_value(&self, name: &str, value: &str) -> bool

Returns true if the calling element has an attribute named name whose value exactly equals value; otherwise returns false.

top
HasChildWithContent
pub fn has_child_with_content(&self, content: &str) -> bool

Returns true if any direct child has text content exactly equal to content; otherwise returns false.

top
HasChildWithTag
pub fn has_child_with_tag(&self, tag_path: &str) -> bool

Returns true if the child selected by tagPath exists; otherwise returns false.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

More Information and Examples
HasChildWithTag using a Tag Path
top
HasChildWithTagAndContent
pub fn has_child_with_tag_and_content(&self, tag_path: &str, content: &str) -> bool

Returns true if the child selected by tagPath exists and its text content exactly equals content; otherwise returns false.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

top
InsertChildTreeAfter
pub fn insert_child_tree_after(&self, index: i32, tree: &Xml)

Inserts the entire subtree referenced by tree as a direct child immediately after the existing child at zero-based index.

If tree belongs to another XML document, the subtree is transferred to the destination tree.

Structural move: The operation preserves the subtree structure. The supplied tree is not flattened into text content.

More Information and Examples
Insert XML into existing XML by calling InsertChildTreeAfter
top
InsertChildTreeBefore
pub fn insert_child_tree_before(&self, index: i32, tree: &Xml)

Inserts the entire subtree referenced by tree as a direct child immediately before the existing child at zero-based index.

If tree belongs to another XML document, the subtree is transferred to the destination tree.

Structural move: The operation preserves the subtree structure. The supplied tree is not flattened into text content.

More Information and Examples
Move XML Subtree to Another XML Document
top
LastChild
pub fn last_child(&self) -> Result<Xml>

Returns an Xml object referencing the last direct child of the calling element.

A common reverse-iteration pattern is LastChild followed by repeated calls to PreviousSibling.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSibling
top
LastChild2
pub fn last_child2(&self) -> Result<()>

Moves the calling Xml object's internal reference to its last direct child. Returns true if a last child exists; otherwise returns false.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSiblingBenefit of XML Methods Having Names Ending in "2"
top
LoadBd
pub fn load_bd(&self, bd: &BinData, auto_trim: bool) -> Result<()>
Introduced in version 9.5.0.77

Parses XML from the bytes contained in bd and replaces the calling object's current XML tree with the loaded document.

If autoTrim is true, leading and trailing whitespace is removed from each leaf element's text content during loading.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadSb
pub fn load_sb(&self, sb: &StringBuilder, auto_trim: bool) -> Result<()>
Introduced in version 9.5.0.62

Parses XML from the current contents of sb and replaces the calling object's current XML tree with the loaded document.

If autoTrim is true, leading and trailing whitespace is removed from each leaf element's text content while loading.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load XML from a Remote URL
top
LoadXml
pub fn load_xml(&self, xml_data: &str) -> Result<()>

Parses the XML text in xmlData and replaces the calling object's current XML tree content with the loaded document root. Returns true if parsing succeeds.

Replacement operation: A successful load replaces the current document/tree state represented by this object; it does not append the loaded XML beneath the current element.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadXml2
pub fn load_xml2(&self, xml_data: &str, auto_trim: bool) -> Result<()>

Parses the XML text in xmlData and replaces the current XML tree, like LoadXml. The autoTrim argument additionally controls whether leading and trailing whitespace is removed from each leaf element's text content while loading.

Whitespace significance: Set autoTrim to false when leading or trailing text whitespace is significant to the application.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Auto-Trim XML Content when Loading
top
LoadXmlFile
pub fn load_xml_file(&self, file_name: &str) -> Result<()>

Reads and parses an XML document from fileName, replacing the calling object's current XML tree with the loaded document root. Returns true on success.

The file's XML declaration and byte encoding are used as part of normal XML parsing.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load XML from Local FilePathLoad XML from a Remote URL
top
LoadXmlFile2
pub fn load_xml_file2(&self, file_name: &str, auto_trim: bool) -> Result<()>

Reads and parses an XML document from fileName, replacing the current XML tree. The autoTrim argument controls whether leading and trailing whitespace is removed from each leaf element's text content.

Whitespace significance: Set autoTrim to false when leading or trailing text whitespace must be preserved exactly.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Auto-Trim XML Content when Loading
top
NewChild
pub fn new_child(&self, tag_path: &str, content: &str) -> Result<Xml>

Creates and returns a new child at tagPath with the specified text content. A new child is created even when a child with the same tag already exists.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed. Use FindOrAddNewChild when duplicate final children should be avoided.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Creating a New Child NodeNewChild using a Tag Path
top
NewChild2
pub fn new_child2(&self, tag_path: &str, content: &str)

Creates a new child at tagPath with the specified text content, but does not return a separate Xml object for the new element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.

More Information and Examples
Creating a New Child NodeXML NewChild2 using a Tag Path
top
NewChildAfter
pub fn new_child_after(&self, index: i32, tag: &str, content: &str) -> Result<Xml>

Creates a new direct child with the specified tag and content, inserts it immediately after the child at zero-based index, and returns the new child element.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML NewChildAfter
top
NewChildBefore
pub fn new_child_before(&self, index: i32, tag: &str, content: &str) -> Result<Xml>

Creates a new direct child with the specified tag and content, inserts it immediately before the child at zero-based index, and returns the new child element.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML NewChildBefore
top
NewChildInt2
pub fn new_child_int2(&self, tag_path: &str, value: i32)

Creates a new child at tagPath whose content is the decimal representation of value. No separate child object is returned.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.

More Information and Examples
Demonstrate the XML NewChildInt2 Method
top
NextInTraversal2
pub fn next_in_traversal2(&self, sb_state: &StringBuilder) -> Result<()>
Introduced in version 9.5.0.77

Moves the calling Xml object to the next element in a depth-first traversal of the tree and updates sbState with the traversal state.

Pass an empty StringBuilder when beginning a traversal, then reuse the same sbState for each subsequent call.

Why the name ends in 2: This method changes the caller's internal element reference. There is no separate NextInTraversal method that returns another Xml object.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Traverse the XML Tree
top
NextSibling
pub fn next_sibling(&self) -> Result<Xml>

Returns an Xml object referencing the current element's next sibling, or no object when there is no next sibling.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSibling
top
NextSibling2
pub fn next_sibling2(&self) -> Result<()>

Moves the calling Xml object's internal reference to its next sibling. Returns true if one exists; otherwise returns false.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about XML methods ending in "2"Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSiblingBenefit of XML Methods Having Names Ending in "2"
top
NumChildrenAt
pub fn num_children_at(&self, tag_path: &str) -> i32
Introduced in version 9.5.0.64

Returns the number of direct children of the element selected by tagPath. Returns -1 if the path does not identify an existing element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

More Information and Examples
Demonstrate the XML "I" PropertyDemonstrate the XML I, J, and K PropertiesGet XML Attribute Value by Path
top
NumChildrenHavingTag
pub fn num_children_having_tag(&self, tag: &str) -> i32

Returns the number of direct children whose tag exactly equals tag. Descendants below those children are not included.

More Information and Examples
Iterate over Direct Children with a Specific TagParsing XML Children Having Identical Tags
top
PreviousSibling
pub fn previous_sibling(&self) -> Result<Xml>

Returns an Xml object referencing the current element's previous sibling, or no object when there is no previous sibling.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSibling
top
PreviousSibling2
pub fn previous_sibling2(&self) -> Result<()>

Moves the calling Xml object's internal reference to its previous sibling. Returns true if one exists; otherwise returns false.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
More information about XML methods ending in "2"Traverse Direct Children via FirstChild / NextSibling, or LastChild / PreviousSiblingBenefit of XML Methods Having Names Ending in "2"
top
PruneAttribute
pub fn prune_attribute(&self, attr_name: &str) -> i32
Introduced in version 9.5.0.77

Recursively traverses the subtree rooted at the calling element and removes every occurrence of the attribute named attrName.

Returns the number of attributes removed.

top
PruneTag
pub fn prune_tag(&self, tag: &str) -> i32
Introduced in version 9.5.0.77

Recursively traverses the subtree rooted at the calling element and removes every element whose tag equals tag. Each removed element's entire descendant subtree is removed with it.

Returns the number of matching tag occurrences removed.

Subtree pruning: When a matching parent is removed, its descendants disappear as part of that subtree; this method is intended for structural cleanup rather than text-only removal.

More Information and Examples
HTML Table to CSV
top
RemoveAllAttributes
pub fn remove_all_attributes(&self) -> Result<()>

Removes every attribute from the calling element. Returns true on success.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
RemoveAllChildren
pub fn remove_all_children(&self)

Removes all direct child elements and their subtrees from the calling element. The calling element's own tag, attributes, and text content are retained.

top
RemoveAttribute
pub fn remove_attribute(&self, name: &str) -> Result<()>

Removes the attribute named name from the calling element. Returns true when the operation succeeds.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
RemoveChild
pub fn remove_child(&self, tag_path: &str)

Removes all child elements selected by tagPath beneath the calling element.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
All matches: This method removes matching children rather than returning a removed subtree. Use an ExtractChild... method when the removed element must be retained.

More Information and Examples
Removing / Deleting Child Nodes from XMLRemoveChild using a Tag Path
top
RemoveChildByIndex
pub fn remove_child_by_index(&self, index: i32)

Removes the direct child at zero-based index, including that child's entire subtree.

More Information and Examples
Removing / Deleting Child Nodes from XML
top
RemoveChildWithContent
pub fn remove_child_with_content(&self, content: &str)

Removes all direct children whose text content exactly equals content, including each removed child's subtree.

More Information and Examples
Removing / Deleting Child Nodes from XML
top
RemoveFromTree
pub fn remove_from_tree(&self)

Detaches the calling element and its entire subtree from its parent. The detached element becomes the root of its own independent XML tree.

Object remains usable: This method removes the subtree from its former document but keeps the calling Xml object referencing the detached subtree.

More Information and Examples
Removing / Deleting Child Nodes from XML
top
RemoveStyleSheet
pub fn remove_style_sheet(&self, attr_name: &str, attr_value: &str) -> i32
Introduced in version 9.5.0.77

Removes XML stylesheet processing instructions whose attribute named attrName has the value attrValue.

Returns the number of matching stylesheet declarations removed, or -1 if an error occurs.

top
SaveBinaryContent
pub fn save_binary_content(&self, filename: &str, unzip_flag: bool, decrypt_flag: bool, password: &str) -> Result<()>

Decodes the binary content stored in this element and writes the resulting bytes to filename. Set unzipFlag and decryptFlag to reverse the transformations originally applied, and supply the corresponding password when decrypting.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SaveXml
pub fn save_xml(&self, file_name: &str) -> Result<()>

Serializes the XML tree or subtree rooted at the current element and writes it to fileName.

Document/output properties such as Encoding, EmitBom, EmitXmlDecl, and EmitCompact affect the generated output as applicable.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
Scrub
pub fn scrub(&self, directives: &str)
Introduced in version 9.5.0.77

Recursively normalizes the XML subtree rooted at the calling element according to the comma-separated keywords in directives.

Supported directives are:

  • AttrTrimEnds - remove leading and trailing whitespace from attribute values.
  • AttrTrimInside - replace tabs, CR, and LF with spaces and collapse repeated spaces inside attribute values.
  • ContentTrimEnds - remove leading and trailing whitespace from element content.
  • ContentTrimInside - normalize internal tabs/line breaks/spaces in element content.
  • LowercaseAttrs - convert attribute names to lowercase.
  • LowercaseTags - convert tag names to lowercase.
  • RemoveCtrl - remove US-ASCII control characters with values 0-31 except TAB, CR, and LF.
Destructive normalization: Scrubbing modifies the tree. Use these options only when the corresponding whitespace, letter case, or control characters are not semantically significant to the application.

More Information and Examples
Scrub Xml
top
SearchAllForContent
pub fn search_all_for_content(&self, after: Option<&Xml>, content_pattern: &str) -> Result<Xml>

Returns the first element whose text content matches contentPattern, regardless of tag name.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Iteration: Pass the element returned by one call as afterPtr on the next call to continue to the next match. Continue until no further element is returned.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML Tree Traversal Order for Search* Methods
top
SearchAllForContent2
pub fn search_all_for_content2(&self, after: Option<&Xml>, content_pattern: &str) -> Result<()>

Performs the same breadth-first content search as SearchAllForContent, but moves the calling Xml object's internal reference to the matching element instead of returning a separate element object.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SearchForAttribute
pub fn search_for_attribute(&self, after: Option<&Xml>, tag: &str, attr: &str, value_pattern: &str) -> Result<Xml>

Returns the first element whose tag equals tag, that has an attribute named attr, and whose attribute value matches valuePattern.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Iteration: Pass the previous match as afterPtr to continue searching after that element.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML SearchForAttribute MethodXML Tree Traversal Order for Search* Methods
top
SearchForAttribute2
pub fn search_for_attribute2(&self, after: Option<&Xml>, tag: &str, attr: &str, value_pattern: &str) -> Result<()>

Performs the same breadth-first tag/attribute search as SearchForAttribute, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SearchForContent
pub fn search_for_content(&self, after: Option<&Xml>, tag: &str, content_pattern: &str) -> Result<Xml>

Returns the first element whose tag equals tag and whose text content matches contentPattern.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Iteration: Pass the previous match as afterPtr to continue searching after that element.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML Tree Traversal Order for Search* Methods
top
SearchForContent2
pub fn search_for_content2(&self, after: Option<&Xml>, tag: &str, content_pattern: &str) -> Result<()>

Performs the same breadth-first tag/content search as SearchForContent, but moves the calling Xml object's internal reference to the matching element.

The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
XML Tree Traversal Order for Search* Methods
top
SearchForTag
pub fn search_for_tag(&self, after: Option<&Xml>, tag: &str) -> Result<Xml>

Returns the first element whose tag exactly equals tag.

The search is breadth-first within the subtree rooted at the caller. afterPtr identifies the element after which searching begins. To begin at the first candidate, use Err where the language binding permits it; ActiveX callers should pass a reference to the caller's element.

Iteration: Pass the previous match as afterPtr to find the next matching tag. Continue until no further element is returned.

Returns Err(chilkat::Error) on failure.

More Information and Examples
XML SearchForTag MethodXML Tree Traversal Order for Search* Methods
top
SearchForTag2
pub fn search_for_tag2(&self, after: Option<&Xml>, tag: &str) -> Result<()>

Performs the same breadth-first tag search as SearchForTag, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.

Use afterPtr in the same way as with SearchForTag to begin or continue the search.

Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Demonstrate XML SearchForTag2
top
SetBinaryContentBd
pub fn set_binary_content_bd(&self, data: &BinData, zip_flag: bool, encrypt_flag: bool, password: &str) -> Result<()>
Introduced in version 11.0.0

Stores the bytes in data as binary content on this element, with optional ZIP compression and optional password-based AES encryption. The stored binary representation is emitted as Base64 text when XML is serialized.

If zipFlag is true, the bytes are compressed first. If encryptFlag is true, the data is encrypted using Chilkat's 128-bit Rijndael/AES format and password.

Returns true on success and false on failure.

Round trip: Use the corresponding binary-content retrieval methods with matching decompression/decryption options to recover the original bytes.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SetBinaryContentFromFile
pub fn set_binary_content_from_file(&self, filename: &str, zip_flag: bool, encrypt_flag: bool, password: &str) -> Result<()>

Reads the bytes from filename and stores them as this element's binary content, with optional ZIP compression and optional password-based encryption. The resulting stored data is represented as Base64 when XML text is generated.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SortByAttribute
pub fn sort_by_attribute(&self, attr_name: &str, ascending: bool)

Sorts the calling element's direct children by the string value of attribute attrName. Set ascending to true for ascending order or false for descending order.

SortCaseInsensitive controls case sensitivity for string sorting.

top
SortByAttributeInt
pub fn sort_by_attribute_int(&self, attr_name: &str, ascending: bool)

Sorts the calling element's direct children numerically by the value of attribute attrName, interpreting each sort value as an integer rather than comparing the text lexicographically.

Set ascending to true for ascending order or false for descending order.

top
SortByContent
pub fn sort_by_content(&self, ascending: bool)

Sorts the calling element's direct children by their text content. Set ascending to true for ascending order or false for descending order.

SortCaseInsensitive controls case sensitivity for the string comparison.

More Information and Examples
XML Sort by Content
top
SortByTag
pub fn sort_by_tag(&self, ascending: bool)

Sorts the calling element's direct children by tag name. Set ascending to true for ascending order or false for descending order.

SortCaseInsensitive controls case sensitivity for the tag-name comparison.

More Information and Examples
XML Sort by Tag
top
SortRecordsByAttribute
pub fn sort_records_by_attribute(&self, sort_tag: &str, attr_name: &str, ascending: bool)

Treats each direct child as a record and sorts those records by the value of attribute attrName on the record's child identified by sortTag.

Set ascending to true for ascending order or false for descending order. String comparisons honor SortCaseInsensitive.

top
SortRecordsByContent
pub fn sort_records_by_content(&self, sort_tag: &str, ascending: bool)

Treats each direct child as a record and sorts those records by the text content of the record's child named sortTag.

Set ascending to true for ascending order or false for descending order. String comparisons honor SortCaseInsensitive.

More Information and Examples
XML Sort Records by Content
top
SortRecordsByContentInt
pub fn sort_records_by_content_int(&self, sort_tag: &str, ascending: bool)

Treats each direct child as a record and sorts those records numerically by the integer content of the record's child named sortTag.

Numeric comparison is used instead of lexicographic string comparison. Set ascending to true for ascending order or false for descending order.

top
SwapNode
pub fn swap_node(&self, node: &Xml) -> Result<()>

Swaps the calling element's tag, text content, and attributes with those of node.

Returns true on success and false on failure.

Children are not swapped: Use SwapTree when child subtrees should also be exchanged.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
SwapTree
pub fn swap_tree(&self, tree: &Xml) -> Result<()>

Swaps the calling element's complete tree state with tree, including tag, text content, attributes, and children.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
TagContent
pub fn tag_content(&self, tag_name: &str) -> Result<String>

Searches the subtree rooted at the calling element for the first element whose tag equals tagName and returns that element's text content.

Recursive search: Unlike direct-child getters, this search is not limited to the caller's immediate children.

Returns Err(chilkat::Error) on failure.

top
TagEquals
pub fn tag_equals(&self, tag: &str) -> bool

Returns true if the calling element's complete tag name, including any namespace prefix, exactly equals tag; otherwise returns false.

top
TagIndex
pub fn tag_index(&self, tag_path: &str) -> i32
Introduced in version 9.5.0.76

Returns the zero-based child index of the element selected by tagPath. Returns -1 when no matching element is found at that path.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
Index meaning: The returned index is the element's position among its parent's direct children, which is the index accepted by methods such as GetChild, RemoveChildByIndex, and the insertion methods.

More Information and Examples
Insert after Node with Tag
top
TagNsEquals
pub fn tag_ns_equals(&self, ns: &str) -> bool
Introduced in version 9.5.0.77

Returns true if this element's namespace-prefix portion exactly equals ns; otherwise returns false.

For example, the namespace prefix of soapenv:Body is soapenv.

Prefix comparison: This compares the lexical prefix, not the namespace URI bound to that prefix.

More Information and Examples
Handling Namespaces in XML Tags
top
TagUnpEquals
pub fn tag_unp_equals(&self, unprefixed_tag: &str) -> bool
Introduced in version 9.5.0.77

Returns true if this element's unprefixed tag exactly equals unprefixedTag; otherwise returns false.

For example, the unprefixed tag of soapenv:Body is Body.

More Information and Examples
Handling Namespaces in XML Tags
top
UnzipContent
pub fn unzip_content(&self) -> Result<()>

Reverses ZipContent: decodes and decompresses the calling element's compressed content and replaces the stored Base64-compressed representation with the original content.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Compress XML Content
top
UnzipTree
pub fn unzip_tree(&self) -> Result<()>

Reverses ZipTree: decompresses the stored representation and reconstructs the calling element's previously compressed subtree.

The element's tag and attributes, which are not replaced by ZipTree, remain associated with the restored tree.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Compress XML Tree
top
UpdateAt
pub fn update_at(&self, tag_path: &str, auto_create: bool, value: &str) -> Result<()>
Introduced in version 9.5.0.64

Sets the text content of the element selected by tagPath to value.

If autoCreate is true, missing elements along the path are created as needed. If it is false, the update requires the target path to already exist.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Demonstrate the XML UpdateAt Method
top
UpdateAttrAt
pub fn update_attr_at(&self, tag_path: &str, auto_create: bool, attr_name: &str, attr_value: &str) -> Result<()>
Introduced in version 9.5.0.64

Sets attribute attrName to attrValue on the element selected by tagPath. The attribute is added when it does not already exist.

If autoCreate is true, missing elements along the path are created as needed. If it is false, the target path must already exist.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Demonstrate the XML UpdateAttrAt MethodXml.UpdateAttrAt Example #2
top
UpdateAttribute
pub fn update_attribute(&self, attr_name: &str, attr_value: &str) -> Result<()>

Sets attribute attrName to attrValue. If the attribute already exists its value is replaced; otherwise the attribute is added.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Update an XML Attribute
top
UpdateAttributeInt
pub fn update_attribute_int(&self, attr_name: &str, value: i32) -> Result<()>

Sets attribute attrName to the decimal representation of integer value. Use UpdateAttribute for string values.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
UpdateChildContent
pub fn update_child_content(&self, tag_path: &str, value: &str)

Sets the text content of the child selected by tagPath to value. Missing elements along the path are automatically created as needed.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

More Information and Examples
UpdateChildContent using a Tag PathXml.ChildContent Example #2
top
UpdateChildContentInt
pub fn update_child_content_int(&self, tag_path: &str, value: i32)

Sets the content of the child selected by tagPath to the decimal representation of integer value.

Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

top
ZipContent
pub fn zip_content(&self) -> Result<()>

ZIP-compresses this element's text content and replaces the original content with Base64-encoded compressed data.

Returns true on success and false on failure.

Reversible transformation: Call UnzipContent to restore the original content.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Compress XML Content
top
ZipTree
pub fn zip_tree(&self) -> Result<()>

ZIP-compresses the calling element's content together with its entire child subtree and replaces that structure with Base64-encoded compressed data.

The calling element's tag and attributes are not changed. Call UnzipTree to reconstruct the compressed subtree.

Returns true on success and false on failure.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Compress XML Tree
top