pugixml 1.14 手册

pugixml 是一个轻量级的 C++ XML 处理库。它包括一个具有丰富遍历/修改功能的类 DOM 接口、一个从 XML 文件/缓冲区构建 DOM 树的超快 XML 解析器，以及一个用于复杂数据驱动树查询的 XPath 1.0 实现。此外，该程序库还支持全部 Unicode 编码，包括两种 Unicode 接口变体以及不同 Unicode 编码之间的转换（在解析/保存过程中自动进行）。pugixml 自 2006 年开始开发和维护，拥有众多用户。所有代码均以 MIT 许可发布，因此可完全免费用于开源和专有应用程序。

pugixml 可以非常快速、方便和节省内存地处理 XML 文档。不过，由于 pugixml 使用的是 DOM 解析器，因此无法处理内存不足的 XML 文档；此外，该解析器是非验证型的，因此如果您需要 DTD 或 XML Schema 验证，那么该库并不适合您。

本手册是 pugixml 的完整手册，详细介绍了该库的所有功能。如果您想尽快开始编写代码，建议您先阅读快速入门指南。

如果您认为发现了 pugixml 中的错误（错误包括编译问题（错误/警告）、崩溃、性能下降和不正确的行为），请通过问题提交表单提交问题。请务必包含相关信息，以便重现错误：pugixml 版本、编译器版本和目标架构、使用 pugixml 并显示错误的代码等。

功能请求的报告方式与 Bug 相同，因此如果您觉得 pugixml 缺少某些功能，或者 API 某些地方不够完善，而您可以提出改进建议，请提交问题。但是请注意，在考虑更改 API 时有很多因素（与以前版本的兼容性、API 冗余等），因此一般来说，不接受无需修改 pugixml 即可通过小函数实现的功能。不过，所有规则都有例外。

如果您对 pugixml 有任何贡献，例如为某些构建系统/IDE 提供构建脚本，或提供一套精心设计的辅助函数，或绑定到 C++ 以外的语言，请提交问题或开启拉取请求。您的贡献必须在与 pugixml 许可证兼容的许可证条款下发布；即不接受 GPL/LGPL 许可证代码。

如果由于隐私或其他原因无法提交问题，您可以直接通过电子邮件与 pugixml 作者联系：arseny.kapoulkine@gmail.com。

pugixml 的开发离不开许多人的帮助；本部分列出了其中的一些人。如果您参与了 pugixml 的开发，但却没有出现在这个名单上，我真的很抱歉；请给我发邮件，以便我能够解决这个问题。

感谢 Kristen Wegner 提供 pugxml 解析器，它是 pugixml 的基础。

感谢 Neville Franks 对 pugxml 解析器的贡献。

感谢 Artyom Palvelev 提出的懒惰间隙收缩法。

感谢 Vyacheslav Egorov 的文档校对和模糊测试。

pugixml 库采用 MIT 许可发布：

这意味着您可以在您的应用程序中自由使用 pugixml，包括开源和专有应用程序。如果您在产品中使用 pugixml，只需在产品发布时添加这样的确认即可：

pugixml 以源代码形式发布。你可以下载源代码或克隆 Git 仓库。

pugixml 以源代码形式发布，没有任何预编译的二进制文件；您必须自行编译。

完整的 pugixml 源代码由三个文件组成：一个源文件 pugixml.cpp 和两个头文件 pugixml.hpp 和 pugiconfig.hpp 。 pugixml.hpp 是使用 pugixml 类/函数时需要包含的主要头文件； pugiconfig.hpp 是补充配置文件（参见附加配置选项）。本指南的其余部分假定 pugixml.hpp 位于当前目录或项目的 include 目录中，这样 #include "pugixml.hpp" 就能找到头文件；不过，你也可以使用相对路径（即 #include "../libs/pugixml/src/pugixml.hpp" ）或 include 目录-相对路径（即 #include <xml/thirdparty/pugixml/src/pugixml.hpp> ）。

pugixml 是用符合标准的 C++ 编写的，在适当的地方使用了一些特定于编译器的变通方法。pugixml 兼容 C++11 标准，但不需要 C++11 支持。每个版本都经过单元测试套件的测试，代码覆盖率超过 99%。

pugixml 可在各种桌面平台（包括 Microsoft Windows、Linux、FreeBSD、Apple MacOSX 和 Sun Solaris）、游戏机（包括 Microsoft Xbox 360、Microsoft Xbox One、Nintendo Wii、Sony Playstation Portable 和 Sony Playstation 3）和移动平台（包括 Android、iOS、BlackBerry、Samsung bada 和 Microsoft Windows CE）上运行。

pugixml 支持多种体系结构，如 x86/x86-64、PowerPC、ARM、MIPS 和 SPARC。一般来说，它可以在任何体系结构上运行，因为它不使用特定于体系结构的代码，也不依赖于未对齐内存访问等功能。

pugixml 可使用任何 C++ 编译器编译；已在 Microsoft Visual C++ 6.0 至 2015 的所有版本、GCC 3.4 至 5.2、Clang 3.2 至 3.7 以及其他各种编译器（例如 Borland C++、Digital Mars C++、Intel C++、Metrowerks CodeWarrior 和 PathScale）上进行了测试。即使在相当高的警告级别下，编写的代码也能避免编译警告。

请注意，某些平台对 C++ 的支持可能非常有限；在某些情况下，您必须使用 PUGIXML_NO_STL 和/或 PUGIXML_NO_EXCEPTIONS 才能顺利编译。这主要适用于老式游戏机和嵌入式系统。

XML 文档用树形数据结构表示。树的根节点是文档本身，对应于 C++ 类型 xml_document。文档有一个或多个子节点，对应于 C++ 类型 xml_node。节点有不同的类型；根据不同的类型，节点可以有一个子节点集合、一个属性集合（对应于 C++ 类型 xml_attribute）和一些附加数据（如名称）。

树节点可以是以下类型之一（它们共同构成枚举 xml_node_type ）：

最后，这里有一个完整的 XML 文档示例和相应的树形表示法（samples/tree.xml）：

尽管有多种节点类型，但表示树的 C++ 类只有三个（ xml_document 、 xml_node 、 xml_attribute ）；对 xml_node 的某些操作只对特定节点类型有效。这些类的描述如下。

xml_document 是整个文档结构的所有者；它是一个不可复制的类。 xml_document 的接口包括加载函数（见加载文档）、保存函数（见保存文档）和 xml_node 的整个接口，后者允许检查和/或修改文档。请注意，虽然 xml_document 是 xml_node 的子类，但 xml_node 并非多态类型；继承的出现只是为了简化使用。您也可以使用 document_element 函数来获取文档的直接子元素节点。

默认构造函数 xml_document 将文档初始化为只有一个根节点（文档节点）的树。然后，可以使用树修改函数或加载函数填充数据；所有加载函数都会销毁之前的树，并占用所有内存，从而使该文档的现有节点/属性句柄处于无效状态。如果要销毁上一棵树，可以使用 xml_document::reset 函数；它会销毁树，并用空树或指定文档的副本取而代之。 xml_document 的销毁函数也会销毁树，因此文档对象的生命周期应超过指向树的节点/属性句柄的生命周期。

xml_node 是文档节点的句柄；它可以指向文档中的任何节点，包括文档节点本身。所有类型的节点都有一个通用接口；可以通过 xml_node::type() 方法查询实际节点类型。请注意， xml_node 只是指向实际节点的句柄，而不是节点本身--你可以有多个句柄指向同一个底层对象。销毁 xml_node 个句柄不会破坏节点，也不会将其从树中删除。 xml_node 句柄的大小等于指针的大小，因此它只不过是指针的一个轻量级封装而已；你可以安全地按值传递或返回6 个对象，而不会产生额外的开销。

有一种类型为 xml_node 的特殊值，称为空节点或空节点（此类节点的类型为 node_null ）。它与任何文档中的任何节点都不对应，因此类似于空指针。然而，所有操作都定义在空节点上；一般情况下，这些操作不做任何事情，并返回空节点/属性或空字符串作为其结果（更多详细信息请参阅特定函数的文档）。这对链式调用非常有用；例如，可以像下面这样获取节点的祖节点： node.parent().parent() ; 如果节点为空节点或没有父节点，则第一次调用会返回空节点；第二次调用也会返回空节点，从而使错误处理更容易。

xml_attribute 是指向 XML 属性的句柄；它的语义与 xml_node 相同，即可以有多个句柄指向同一个底层对象，并且有一个特殊的空属性值，它会传播到函数结果中。

xml_node 和 xml_attribute 的默认构造函数都会将它们初始化为空对象。

xml_node 和 xml_attribute 的行为类似于指针，也就是说，它们可以与同类型的其他对象进行比较，因此可以用作关联容器中的键。指向同一底层对象的所有句柄都是等价的，而指向不同底层对象的任何两个句柄都是不等价的。空句柄只能与空句柄进行比较。关系比较的结果不能通过文件中节点的顺序或任何其他方式可靠地确定。除搜索优化（即关联容器键）外，请勿使用关系比较操作符。

如果要在基于散列的关联容器中使用 xml_node 或1 个对象作为键，可以使用 hash_value 个成员函数。它们返回的哈希值保证所有指向同一底层对象的句柄都相同。请注意，哈希值并不取决于节点的内容，而只取决于底层结构在内存中的位置，这意味着两次加载同一文档可能会产生不同的哈希值，而复制节点也不会保留哈希值。

最后，句柄可以隐式地转换为布尔对象，这样就可以用以下代码测试节点/属性是否为空： if (node) { …​ } 或 if (!node) { …​ } else { …​ } 。另外，也可以通过调用以下方法来检查给定的 xml_node / xml_attribute 句柄是否为空：

如果没有文档树，节点和属性是不存在的，因此如果不将它们添加到某个文档中，就无法创建它们。一旦底层节点/属性对象被销毁，这些对象的句柄就会失效。这意味着销毁整个树会使所有节点/属性句柄失效，同时也意味着销毁子树（通过调用 xml_node::remove_child ）或删除属性会使相应的句柄失效。我们无法检查句柄的有效性，因此必须通过外部机制来确保其正确性。

在配置 pugixml 时，有两种接口和内部表示法可供选择：可以选择 UTF-8（也称 char）接口，也可以选择 UTF-16/32（也称 wchar_t）接口。选择由 PUGIXML_WCHAR_MODE 定义控制；您可以通过 pugiconfig.hpp 或预处理选项设置该定义，详见附加配置选项。如果设置了该定义，则使用 wchar_t 接口；否则（默认情况下）使用 char 接口。确切的宽字符编码假定为 UTF-16 或 UTF-32，并根据 wchar_t 类型的大小确定。

所有处理字符串的树函数都处理 C 风格空尾字符串或所选字符类型的 STL 字符串。例如，节点名称访问器在 char 模式下如下所示：

而在 wchar_t 模式下则是这样：

有一种特殊的类型 pugi::char_t ，它被定义为字符类型，取决于库的配置。还有一种类型 pugi::string_t ，它被定义为字符类型的 STL 字符串；在 char 模式下对应于 std::string ，在 wchar_t 模式下对应于 std::wstring 。

除了接口之外，内部实现也会改变，将 XML 数据存储为 pugi::char_t ；这意味着这两种模式具有不同的内存使用特性--一般来说，UTF-8 模式更节省内存和性能，尤其是当 sizeof(wchar_t) 为 4 时。在加载文档时自动转换为 pugi::char_t ，在保存文档时自动转换为 pugi::char_t ，这也会带来轻微的性能损失。不过，一般建议是根据使用情况来选择字符模式，例如，如果 UTF-8 处理起来不方便，而且大部分 XML 数据都是非 ASCII 格式，那么 wchar_t 模式可能是更好的选择。

在某些情况下，您需要在 UTF-8 和 wchar_t 编码之间转换字符串数据：

这两个函数都接受一个空尾字符串作为参数 str ，并返回转换后的字符串。 as_utf8 执行从 UTF-16/32 到 UTF-8 的转换； as_wide 执行从 UTF-8 到 UTF-16/32 的转换。无效的 UTF 序列会在转换时被默默丢弃。 str 必须是有效的字符串；传递空指针会导致未定义的行为。还有两个重载具有相同的语义，接受一个字符串作为参数：

pugixml 中几乎所有函数都有以下线程安全保证：

同时修改和遍历一棵树需要同步，例如通过读写器锁。修改包括更改文档结构和更改单个节点/属性数据，即更改名称/值。

唯一的例外是 set_memory_management_functions；它修改全局变量，因此不是线程安全的。它的使用策略有更多限制，请参阅自定义内存分配/去分配函数。

除了 XPath 之外，pugixml 本身不会抛出任何异常。此外，大多数 pugixml 函数都有不抛出异常的保证。

这不适用于对 STL 字符串或 IOstreams 进行操作的函数；此类函数要么有强保证（对字符串进行操作的函数），要么有基本保证（对流进行操作的函数）。此外，调用用户自定义回调（即 xml_node::traverse 或 xml_node::find_node）的函数除了回调提供的异常保证外，不提供任何异常保证。

如果未使用 PUGIXML_NO_EXCEPTIONS 定义禁用异常处理，XPath 函数可能会在解析错误时抛出 xpath_exception；在内存不足的情况下，XPath 函数也可能抛出 std::bad_alloc 。尽管如此，XPath 函数还是提供了强有力的异常保证。

pugixml 以大块方式请求文档存储所需的内存，并在这些大块中分配文档数据。本节将讨论用于分块分配和内部内存管理的替换函数。

XML 数据最常见的来源是文件；pugixml 提供了从文件加载 XML 文档的专用函数：

这些函数的第一个参数是文件路径，另外还有两个可选参数，分别指定解析选项（请参阅解析选项）和输入数据编码（请参阅编码）。路径具有目标操作系统格式，因此可以是相对路径，也可以是绝对路径；路径应具有目标系统的分隔符；如果目标文件系统区分大小写，路径应具有准确的大小写等。

在第一个函数（接受 const char* path ）中，文件路径被原封不动地传递给系统文件打开函数；第二个函数要么使用运行时库提供的特殊文件打开函数，要么将路径转换为 UTF-8 并使用系统文件打开函数。

load_file 会销毁现有的文档树，然后尝试从指定文件中加载新的文档树。操作结果将以 xml_parse_result 对象形式返回；该对象包含操作状态和相关信息（即如果解析失败，输入文件中最后一个成功解析的位置）。有关错误处理的详细信息，请参阅处理解析错误。

这是一个从文件（samples/load_file.cpp）加载 XML 文档的示例：

有时，XML 数据应从文件以外的其他来源（即 HTTP URL）加载；您可能还希望使用非标准功能从文件加载 XML 数据，即使用虚拟文件系统设施或从 GZip 压缩文件加载 XML。所有这些情况都需要从内存中加载文档。首先，您应该准备一个包含所有 XML 数据的连续内存块；然后，您必须调用其中一个缓冲区加载函数。这些函数将处理必要的编码转换（如果有的话），然后将数据解析为相应的 XML 树。有多种缓冲区加载函数，它们的行为各不相同，因此在性能/内存使用方面也不尽相同：

所有函数都接受以 XML 数据指针 contents 和数据大小（字节）表示的缓冲区。此外，还有两个可选参数，分别指定解析选项（参见解析选项）和输入数据编码（参见编码）。缓冲区不必以 0 结尾。

load_buffer 函数使用不可变缓冲区工作--它不会修改缓冲区。由于这一限制，它必须创建一个私有缓冲区，并在解析前将 XML 数据复制到缓冲区（必要时进行编码转换）。这种复制操作会对性能造成影响，因此需要使用就地函数 load_buffer_inplace 和 load_buffer_inplace_own 将文档数据存储到缓冲区中，并在此过程中对其进行修改。如果使用置换函数，为了使文档保持有效，必须确保缓冲区的生命周期超过树的生命周期。此外， load_buffer_inplace 不会承担缓冲区的所有权，所以你必须自己销毁它； load_buffer_inplace_own 会承担缓冲区的所有权，并在不需要时将其销毁。这意味着如果使用 load_buffer_inplace_own ，就必须使用 pugixml 分配函数分配内存（可通过 get_memory_allocation_function 获取）。

从性能/内存的角度来看，最好的方法是使用 load_buffer_inplace_own 加载文档；该函数可以最大限度地控制 XML 数据的缓冲区，因此可以避免多余的拷贝，并在解析时减少内存的峰值使用。如果必须从内存中加载文档，且性能至关重要，建议使用此函数。

还有一个简单的辅助函数，可用于从空端字符串加载 XML 文档：

它相当于调用 load_buffer ，而 size 则是 strlen(contents) 或 wcslen(contents) * sizeof(wchar_t) ，具体取决于字符类型。该函数假定输入数据为本地编码，因此不会进行任何编码转换。一般来说，该函数适用于从字符串文字加载小型文档，但与缓冲区加载函数相比，开销更大，功能更少。

这是一个使用不同函数从内存加载 XML 文档的示例（samples/load_memory.cpp）：

为了增强互操作性，pugixml 提供了从任何实现 C++ std::istream 接口的对象加载文档的函数。这允许你从任何标准 C++ 流（如文件流）或任何第三方兼容实现（如 Boost Iostreams）中加载文档。有两个函数，一个适用于窄字符流，另一个适用于宽字符流：

load 带有1 个参数，从当前读取位置到末尾加载数据流中的文档，将数据流内容视为指定编码的字节流（必要时进行编码自动检测）。因此，在已打开的 std::ifstream 对象上调用 xml_document::load 相当于调用 xml_document::load_file 。

load 和 std::wstream 参数将流内容视为宽字符流（编码始终为 encoding_wchar）。因此，在宽字符流中使用 load 时，需要进行仔细的（通常是特定平台的）流设置（即使用 imbue 函数）。一般情况下，我们不鼓励使用宽字符流，但宽字符流提供了加载非 Unicode 编码文档的能力，例如，如果设置了正确的本地语言，就可以加载 Shift-JIS 编码的数据。

这是一个使用流（samples/load_stream.cpp）从文件加载 XML 文档的简单示例；如需了解涉及宽流和本地的更复杂示例，请阅读示例代码：

所有文档加载函数都通过 xml_parse_result 对象返回解析结果。它包含解析状态、从源流开头到最后一个成功解析字符的偏移量以及源流的编码：

解析状态用 xml_parse_status 枚举表示，可以是以下其中之一：

description() 成员函数可用于将解析状态转换为字符串；返回的信息始终为英文，因此如果需要本地化字符串，则必须编写自己的函数。但请注意， description() 函数返回的确切信息可能会因版本不同而有所变化，因此任何复杂的状态处理都应基于 status 的值。请注意，即使在 PUGIXML_WCHAR_MODE 中， description() 也会返回4 个字符串；您必须调用 as_wide 才能获得6 个字符串。

如果由于源数据不是有效的 XML 而导致解析失败，生成的树并不会被破坏--尽管加载函数返回错误信息，但仍可使用已成功解析的树的一部分。显然，最后一个元素的名称/值可能会出乎意料；例如，如果属性值没有以必要的引号结束（如 <node attr="value>some data</node> 示例），属性 attr 的值将包含字符串 value>some data</node> .

除了状态代码外，解析结果还有一个 offset 成员，其中包含最后一个成功解析字符的偏移量（如果解析因源数据中的错误而失败）；否则 offset 为 0。 出于提高解析效率的考虑，pugixml 在解析过程中不跟踪当前行；该偏移量以 pugi::char_t 为单位（字符模式为字节，宽字符模式为宽字符）。许多文本编辑器都支持 "转到位置"（Go To Position）功能--你可以用它来定位准确的错误位置。另外，如果从内存中加载文档，也可以显示错误块和错误描述（见下面的示例代码）。

解析结果还有一个 encoding 成员，可用于检查源数据编码是否猜对。它等于解析过程中使用的精确编码（即精确的字节序）；更多信息请参阅编码。

解析结果对象可以隐式转换为 bool ；如果不想彻底处理解析错误，可以直接检查加载函数的返回值，将其视为 bool : if (doc.load_file("file.xml")) { …​ } else { …​ } 。

这是一个处理加载错误的示例 ( samples/load_error_handling.cpp)：

所有文档加载函数都接受可选参数 options 。这是一个位掩码，用于自定义解析过程：您可以选择解析的节点类型以及对 XML 文本执行的各种转换。禁用某些转换可以提高某些文档的解析性能；但是，所有转换的代码都经过了很好的优化，因此大多数文档都不会获得任何性能上的好处。根据经验，只有当您想获取文档中默认排除的某些节点（如声明或注释节点）时，才修改解析标志。

这些标志控制着生成的树内容：

这些标志控制着树元素内容的转换：

此外，还有三个预定义的选项屏蔽：

这是一个使用不同解析选项的示例 ( samples/load_options.cpp)：

pugixml 支持所有流行的 Unicode 编码（UTF-8、UTF-16（大内码和小内码）、UTF-32（大内码和小内码）；由于 UCS-2 是 UTF-16 的严格子集，因此自然也支持 UCS-2）以及一些非 Unicode 编码（Latin-1），并处理所有编码转换。大多数加载函数接受可选参数 encoding 。这是一个枚举类型 xml_encoding 的值，可以有以下值：

对于所有格式良好的 XML 文档（因为它们以文档声明开头）和所有其他以 < 开头的 XML 文档，用于 encoding_auto 的算法可正确检测任何受支持的 Unicode 编码；如果您的 XML 文档不是以 < 开头，且编码不同于 UTF-8，请使用特定编码。

pugixml 并不完全符合 W3C 标准--它可以加载任何有效的 XML 文档，但不执行某些良好格式检查。虽然 pugixml 已做出相当大的努力来拒绝无效的 XML 文档，但出于性能方面的考虑，某些验证并没有执行。

在处理有效的 XML 文档时，只有一种不符合规范的行为：pugixml 不会使用文档类型声明中提供的信息进行解析。这意味着 DOCTYPE 中声明的实体不会被展开，所有属性/PCDATA 值始终以统一的方式处理，仅取决于解析选项。

至于拒绝无效的 XML 文档，有许多与 W3C 规范不兼容的地方，包括

文档的内部表示形式是一棵树，每个节点都有一个子节点列表（子节点的顺序与 XML 表示形式中的顺序一致），此外，元素节点还有一个属性列表，也是有序的。为了让你从树中的一个节点到另一个节点，我们提供了几个函数。这些函数与内部表示法大致对应，因此通常是其他遍历方法的基础模块（即 XPath 遍历基于这些函数）。

parent 返回节点的父节点；除文档外，所有非空节点的父节点都是非空的。 first_child 和 last_child 分别返回节点的第一个和最后一个子节点；请注意，只有文档节点和元素节点可以有非空的子节点列表。如果节点没有子节点，两个函数都返回空节点。 next_sibling 和 previous_sibling 分别返回子节点列表中紧靠该节点右侧/左侧的节点--例如，在 <a/><b/><c/> 中，调用 next_sibling 获取指向 <b/> 的句柄会得到指向 <c/> 的句柄，而调用 previous_sibling 则会得到指向 <a/> 的句柄。如果节点没有下一个/上一个兄弟节点（如果它分别是列表中的最后一个/第一个节点），函数将返回空节点。 first_attribute , last_attribute , next_attribute 和 previous_attribute 函数的行为与相应的子节点函数类似，允许以相同的方式遍历属性列表。

在 null 句柄上调用上述任何函数都会产生一个 null 句柄，即 node.first_child().next_sibling() 返回 node 的第二个子节点，如果 node 为空、没有子节点或只有一个子节点，则返回 null 句柄。

使用这些函数，可以遍历所有子节点并显示所有属性，就像这样（samples/traverse_base.cpp）：

除了结构信息（父节点、子节点、属性）外，节点还可以有名称和值，两者都是字符串。node_document 节点没有名称或值，node_element 和 node_declaration 节点始终有名称但没有值，node_pcdata、node_cdata、node_comment 和 node_doctype 节点始终有值但没有名称（可能为空），node_pi 节点始终有名称和值（同样，值可能为空）。要获取节点的名称或值，可以使用以下函数：

如果节点没有名称或值，或者节点句柄为空，这两个函数都会返回空字符串，而不会返回空指针。

将数据存储为某个节点（即 <node><description>This is a node</description></node> ）的文本内容很常见。在这种情况下， <description> 节点没有值，但有一个值为 "This is a node" 的 node_pcdata 类型的子节点。 pugixml 提供了几个辅助函数来解析此类数据：

child_value() 返回 node_pcdata 或 node_cdata 类型的第一个子节点的值； child_value(name) 是 child(name).child_value() 的简单封装。在上例中，调用 node.child_value("description") 和 description.child_value() 都会产生字符串 "This is a node" 。如果没有相关类型的子节点，或者句柄为空， child_value 功能将返回空字符串。

text() 返回一个特殊对象，该对象可用于在更复杂的情况下处理 PCDATA 内容，而不仅仅是检索值；有关该对象的描述，请参阅处理文本内容章节。

下一节末将举例说明如何使用其中的一些功能。

所有属性都有 name 和 value，两者都是字符串（value 可以为空）。有两个相应的访问器，如 xml_node ：

如果属性句柄为空，这两个函数都会返回空字符串，而不会返回空指针。

如果在属性句柄为空的情况下需要一个非空字符串（例如，需要从 XML 属性中获取选项值，但如果没有指定，则需要默认为 "sorted" 而不是 "" ），可以使用 as_string 访问器：

如果属性句柄为空，则返回 def 参数。如果不指定参数，则函数等价于 value() 。

在许多情况下，属性值的类型并不是字符串，例如，一个属性可能总是包含应被视为整数的值，尽管在 XML 中它们被表示为字符串：

as_int , as_uint , as_llong , as_ullong , as_double 和 as_float 将属性值转换为数字。如果属性句柄为空，将返回6 个参数（默认为 0）。否则，所有前导空白字符将被截断，剩余字符串将被解析为十进制或十六进制形式的整数（适用于 as_int , as_uint , as_llong 和 as_ullong ；如果数字前缀为 0x 或 0X ，则使用十六进制格式），或十进制或科学数形式的浮点数（ as_double 或 as_float ）。

如果输入字符串包含非数字字符序列或超出目标数字范围的数字，结果将是未定义的。

as_bool 将属性值转换为布尔值的方法如下：如果属性句柄为空，则返回1 个参数（默认为 false ）。如果属性值为空，则返回 false 。否则，如果第一个字符是 '1', 't', 'T', 'y', 'Y' 中的一个，则返回 true 。这意味着 "true" 和 "yes" 这样的字符串会被识别为 true ，而 "false" 和 "no" 这样的字符串会被识别为 false 。要实现更复杂的匹配，您需要编写自己的函数。

这是一个使用这些函数以及节点数据检索函数的示例（samples/traverse_base.cpp）：

由于大量的文档遍历包括查找具有正确名称的节点/属性，因此有专门的函数用于此目的：

child 和 attribute 返回具有指定名称的第一个子代/属性； next_sibling 和 previous_sibling 返回相应方向上具有指定名称的第一个同胞。所有字符串比较均区分大小写。如果节点句柄为空或没有指定名称的节点/属性，则返回空句柄。

child 和 next_sibling 函数一起使用，可以像这样循环遍历具有所需名称的所有子节点：

attribute 函数需要根据名称查找目标属性。如果一个节点有很多属性，按名称查找每个属性会很耗时。如果你知道节点中的属性是如何排序的，就可以使用更快的函数：

额外的 hint 参数用于猜测属性可能所在的位置，并更新为下一个属性的位置，这样如果以正确的顺序搜索多个属性，就能最大限度地提高性能。请注意， hint 必须为空，或者必须属于节点，否则其行为将是未定义的。

该功能的使用方法如下：

无论属性的顺序如何，这段代码都是正确的，但如果 "id" 、 "name" 和 "version" 按顺序出现，速度会更快。

有时，所需的节点不是由唯一名称指定的，而是由某些属性的值指定的；例如，节点集合很常见，每个节点都有一个唯一的 id： <group><item id="1"/> <item id="2"/></group> 。有两个函数可以根据属性值查找子节点：

三参数函数返回具有指定名称的第一个子节点，该节点具有指定名称/值的属性；二参数函数跳过节点名称测试，这对于在异构集合中搜索非常有用。如果节点句柄为空或未找到节点，则返回空句柄。所有字符串比较都区分大小写。

在上述所有函数中，所有参数都必须是有效字符串；传递空指针会导致未定义的行为。

这是一个使用这些函数的示例 ( samples/traverse_base.cpp)：

如果您的 C++ 编译器支持基于范围的 for-loop（这是 C++11 的特性，在撰写本文时，Microsoft Visual Studio 2012+、GCC 4.6+ 和 Clang 3.0+ 均支持该特性），您就可以使用它来枚举节点/属性。为支持这一功能，我们还提供了额外的辅助工具；请注意，这些辅助工具也兼容 Boost Foreach 以及其他可能是 C++11 之前的 foreach 设施。

使用 children 函数可以枚举所有子节点；使用带有 name 个参数的 children 函数可以枚举具有特定名称的所有子节点；使用 attributes 函数可以枚举节点的所有属性。请注意，您也可以在基于范围的 for 结构中使用节点对象本身，这等同于使用 children() .

这是一个使用这些函数的示例 ( samples/traverse_rangefor.cpp)：

使用"0"可以清楚地表达代码的意图，但请注意，每个节点都可以被视为子节点的容器，因为它提供了下一节描述的 begin() / end() 成员函数。因此，只需使用节点本身，就可以遍历节点的子节点：

子节点列表和属性列表是简单的双链列表；虽然可以使用 previous_sibling / next_sibling 和其他类似函数进行迭代，但 pugixml 还提供了节点和属性迭代器，因此可以将节点视为其他节点或属性的容器：

begin 和 attributes_begin 将分别返回指向第一个节点/属性的迭代器； end 和 attributes_end 将分别返回节点/属性列表的过终点迭代器--该迭代器不能被取消引用，但递减它将导致迭代器指向列表中的最后一个元素（空列表除外，递减过终点迭代器将导致未定义的行为）。过终点迭代器通常用作迭代循环的终止值（见下面的示例）。如果想获得指向现有句柄的迭代器，可以将句柄作为单个构造函数参数来构造迭代器，如下所示： xml_node_iterator(node) .对于 xml_attribute_iterator ，你必须同时提供一个属性和它的父节点。

如果在空节点上调用， begin 和 end 返回相等的迭代器；这种迭代器不能被取消引用。 attributes_begin 和 attributes_end 的行为方式相同。为了正确使用迭代器，这意味着空节点的子节点/属性集合看起来是空的。

这两种类型的迭代器都具有双向迭代器语义（即可以递增和递减，但不支持有效的随机访问），并支持所有常用的迭代器操作--比较、取消引用等。如果迭代器指向的节点/属性对象被从树中删除，迭代器就会失效；添加节点/属性不会使任何迭代器失效。

下面是一个使用迭代器进行文档遍历的示例（samples/traverse_iter.cpp）：

上述方法允许遍历某个节点的直接子节点；如果要进行深度树遍历，则必须通过递归函数或其他类似方法。不过，pugixml 提供了一个子树深度优先遍历的辅助工具。要使用它，必须实现0 个接口并调用1 个函数：

通过调用遍历根上的 traverse 函数启动遍历，过程如下

如果 begin 、 end 或 for_each 中的任何一个调用返回 false ，则遍历结束， false 作为遍历结果返回；否则，遍历结果为 true 。请注意，您不必覆盖 begin 或 end 函数；它们的默认实现返回 true 。

您可以通过调用 depth 函数来获取节点相对于遍历根的深度。如果从 begin / end 处调用，则返回 -1 ；如果从 for_each 处调用，则返回基于 0 的深度--遍历根的所有子节点的深度为 0，所有孙节点的深度为 1，以此类推。

这是使用 xml_tree_walker ( samples/traverse_walker.cpp) 遍历树层次结构的示例：

虽然现有函数可以获取已知内容的节点/属性，但它们往往不足以满足简单查询的需要。作为手动遍历节点/属性直到找到所需的节点/属性的替代方法，您可以创建一个谓词并调用 find_ 个函数中的一个：

谓词应该是一个普通函数或函数对象，它接受一个类型为 xml_attribute （对于 find_attribute ）或 xml_node （对于 find_child 和 find_node ）的参数，并返回 bool 。在调用谓词时，不能将空句柄作为参数。

find_attribute 函数遍历指定节点的所有属性，并返回谓词返回 true 的第一个属性。如果所有属性的谓词返回值都是 false ，或者没有任何属性（包括节点为空的情况），则返回空属性。

find_child 函数遍历指定节点的所有子节点，并返回谓词返回 true 的第一个节点。如果所有节点的谓词返回值都是 false ，或者没有子节点（包括节点为空的情况），则返回空节点。

find_node 函数对指定节点的子树（不包括节点本身）执行深度优先遍历，并返回谓词返回 true 的第一个节点。如果所有节点的谓词返回值都是 false ，或者子树为空，则返回空节点。

这是一个使用基于谓词的函数的示例 ( samples/traverse_predicate.cpp)：

将数据存储为某个节点（即 <node><description>This is a node</description></node> ）的文本内容是很常见的。pugixml 提供了一个特殊类 xml_text 来处理此类数据。在修改文档数据的文档中介绍了如何使用文本对象来修改数据；本节将介绍 xml_text 的访问接口。

您可以使用 text() 方法从节点获取文本对象：

如果节点的类型为 node_pcdata 或 node_cdata ，则使用节点本身来返回数据；否则，使用类型为 node_pcdata 或 node_cdata 的第一个子节点。

您可以使用布尔值（即 if (text) { …​ } 或 if (!text) { …​ } ）来检查文本对象是否绑定到有效的 PCDATA/CDATA 节点。或者，您也可以使用 empty() 方法进行检查：

如果给定了一个文本对象，您可以使用以下函数获取其内容（即 PCDATA/CDATA 节点的值）：

如果文本对象为空，函数将返回空字符串，而不会返回空指针。

如果文本对象为空，或者文本内容实际上是以字符串形式存储的数字或布尔值，则需要非空字符串，这时可以使用以下访问器：

上述所有函数的语义都与类似的 xml_attribute 成员相同：如果文本对象为空，它们会返回默认参数，并使用相同的规则和限制将文本内容转换为目标类型。有关详细信息，请参阅属性函数文档。

xml_text 本质上是一个对 xml_node 值进行操作的辅助类。它与 node_pcdata 或 node_cdata 类型的节点绑定。您可以使用下面的函数检索该节点：

从本质上讲，假设 text 是一个 xml_text 对象，那么调用 text.get() 就等同于调用 text.data().value() 。

这是一个使用 xml_text 对象的示例（samples/text.cpp）：

如果需要获取某个节点的文档根目录，可以使用下面的函数：

此函数返回 node_document 类型的节点，即节点所属文档的根节点（除非节点为空，否则返回空节点）。

虽然 pugixml 支持复杂的 XPath 表达式，但有时也需要一个简单的路径处理工具。有两个函数，分别用于获取节点路径和将路径转换为节点：

节点路径由节点名组成，节点名之间用分隔符（默认为 / ）分隔；路径还可以包含 self ( . ) 和 parent ( .. ) 伪名，因此这是一个有效的路径： "../../foo/./bar" . path 返回从文档根指向节点的路径， first_element_by_path 寻找给定路径所代表的节点；路径可以是绝对路径（绝对路径以分隔符开始），在这种情况下，路径的其余部分被视为文档根相对路径和给定节点的相对路径。例如，在下面的文档中 <a><b><c/></b></a> , 节点 <c/> 的路径为 "a/b/c" ；调用路径为 "a/b" 的文档 first_element_by_path ，结果为节点 <b/> ；调用路径为 "../a/./b/../." 的节点 <a/> 的路径 first_element_by_path ，结果为节点 <a/> ；调用路径为 "/a" 的节点 first_element_by_path ，结果为任意节点的节点 <a/> 。

如果路径组件模棱两可（如果有两个节点具有给定的名称），则选择第一个；路径不能保证唯一标识文档中的节点。如果找不到路径的任何组件， first_element_by_path 的结果是空节点；对于空节点， first_element_by_path 也返回空节点，在这种情况下，路径并不重要。对于空节点， path 返回空字符串。

出于提高效率的考虑，pugixml 在解析时不会记录节点的行/列信息。但是，如果节点在解析后没有发生重大变化（名称/值没有变化，节点本身是原始节点，即没有从树中删除，之后又重新添加），则可以从 XML 缓冲区的起始位置获取偏移量：

如果偏移量不可用（如果节点为空、最初不是从流中解析的，或者发生了重大变化），函数将返回-1。否则，函数将以 pugi::char_t 为单位，返回节点数据从 XML 缓冲区开始的偏移量。有关解析偏移量的更多信息，请参阅解析错误处理文档。

如前所述，节点可以有名称和值，两者都是字符串。node_document 节点没有名称或值，node_element 和 node_declaration 节点总是有名称但没有值，node_pcdata、node_cdata、node_comment 和 node_doctype 节点没有名称但总是有值（可能为空），node_pi 节点总是有名称和值（同样，值可能为空）。要设置节点的名称或值，可以使用以下函数：

这两个函数都会尝试将名称/值设置为指定的字符串，并返回操作结果。如果节点没有名称或值（例如，在 node_pcdata 节点上调用 set_name 时）、节点句柄为空或内存不足以处理请求，则操作失败。提供的字符串会被复制到文档管理的内存中，并可在函数返回后销毁（例如，可以安全地将堆栈分配的缓冲区传递给这些函数）。名称/值内容未经验证，因此请注意只使用有效的 XML 名称，否则文档可能会畸形。

这是一个设置节点名称和值的示例 ( samples/modify_base.cpp)：

所有属性都有 name 和 value，两者都是字符串（value 可以为空）。您可以使用以下函数设置它们：

这两个函数都会尝试将名称/值设置为指定的字符串，并返回操作结果。如果属性句柄为空，或内存不足以处理请求，则操作失败。提供的字符串会被复制到文档管理的内存中，并可在函数返回后销毁（例如，可以安全地将堆栈分配的缓冲区传递给这些函数）。名称/值内容未经验证，因此请注意只使用有效的 XML 名称，否则文档可能会畸形。

除字符串函数外，还提供了几个函数用于处理以数字和布尔值为值的属性：

上述函数将参数转换为字符串，然后调用基 set_value 函数。整数被转换为十进制形式，浮点数被转换为十进制或科学数形式（取决于数字大小），布尔值被转换为 "true" 或 "false" 。

为方便起见，所有 set_value 函数都有相应的赋值操作符：

这些运算符只需调用右边的 set_value 函数，并返回所调用的属性；返回值为 set_value 时将被忽略，因此错误也将被忽略。

这是一个设置属性名和值的示例 ( samples/modify_base.cpp)：