From 160c1c23d9ccf40b5d8bbffa591483a2d7fe3d9f Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Fri, 25 Jan 2019 16:42:25 -0800 Subject: [PATCH] docs: Improve null node comparison wording Change confusing wording: null nodes compare as equal to null handles, the previous wording implied that each null handle is unique --- docs/manual.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manual.adoc b/docs/manual.adoc index 0b91e1e..9600bcf 100644 --- a/docs/manual.adoc +++ b/docs/manual.adoc @@ -380,7 +380,7 @@ There is a special value of `xml_node` type, known as null node or empty node (s Both `xml_node` and `xml_attribute` have the default constructor which initializes them to null objects. [[xml_attribute::comparison]][[xml_node::comparison]] -`xml_node` and `xml_attribute` try to behave like pointers, that is, they can be compared with other objects of the same type, making it possible to use them as keys in associative containers. All handles to the same underlying object are equal, and any two handles to different underlying objects are not equal. Null handles only compare as equal to themselves. The result of relational comparison can not be reliably determined from the order of nodes in file or in any other way. Do not use relational comparison operators except for search optimization (i.e. associative container keys). +`xml_node` and `xml_attribute` try to behave like pointers, that is, they can be compared with other objects of the same type, making it possible to use them as keys in associative containers. All handles to the same underlying object are equal, and any two handles to different underlying objects are not equal. Null handles only compare as equal to null handles. The result of relational comparison can not be reliably determined from the order of nodes in file or in any other way. Do not use relational comparison operators except for search optimization (i.e. associative container keys). [[xml_attribute::hash_value]][[xml_node::hash_value]] If you want to use `xml_node` or `xml_attribute` objects as keys in hash-based associative containers, you can use the `hash_value` member functions. They return the hash values that are guaranteed to be the same for all handles to the same underlying object. The hash value for null handles is 0. Note that hash value does not depend on the content of the node, only on the location of the underlying structure in memory - this means that loading the same document twice will likely produce different hash values, and copying the node will not preserve the hash.