summaryrefslogtreecommitdiff
path: root/documentation/cxx/tree
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2010-01-22 15:40:12 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2010-01-22 15:40:12 +0200
commitf60df03e3cedb86508645357e17003eb9281f31a (patch)
treed65c9cd62a6500b7d0f8303caf64797d08f508c0 /documentation/cxx/tree
parent55ffb84acf75d3fa475dfe21d053e404eb753e5a (diff)
Add support for detaching subtrees in C++/Tree
New option: --generate-detach. New test: cxx/tree/detach.
Diffstat (limited to 'documentation/cxx/tree')
-rw-r--r--documentation/cxx/tree/manual/index.xhtml89
1 files changed, 76 insertions, 13 deletions
diff --git a/documentation/cxx/tree/manual/index.xhtml b/documentation/cxx/tree/manual/index.xhtml
index c00be9e..695a72e 100644
--- a/documentation/cxx/tree/manual/index.xhtml
+++ b/documentation/cxx/tree/manual/index.xhtml
@@ -2737,6 +2737,27 @@ public:
};
</pre>
+ <p>In addition, if requested by specifying the <code>--generate-detach</code>
+ option and only for members of non-fundamental C++ types, the mapping
+ provides a detach function that returns an automatic pointer to the
+ member's type, for example:</p>
+
+ <pre class="c++">
+class object: xml_schema::type
+{
+public:
+ ...
+
+ std::auto_ptr&lt;member_type>
+ detach_member ();
+ ...
+
+};
+ </pre>
+
+ <p>This function detaches the value from the tree leaving the member
+ value uninitialized. Accessing such an uninitialized value prior to
+ re-initializing it results in undefined behavior.</p>
<p>The following code shows how one could use this mapping:</p>
@@ -2746,14 +2767,16 @@ f (object&amp; o)
{
using xml_schema::string;
- string s (o.member ()); // get
+ string s (o.member ()); // get
object::member_type&amp; sr (o.member ()); // get
- o.member ("hello"); // set, deep copy
- o.member () = "hello"; // set, deep copy
+ o.member ("hello"); // set, deep copy
+ o.member () = "hello"; // set, deep copy
std::auto_ptr&lt;string> p (new string ("hello"));
- o.member (p); // set, assumes ownership
+ o.member (p); // set, assumes ownership
+ p = o.detach_member (); // detach, member is uninitialized
+ o.member (p); // re-attach
}
</pre>
@@ -2907,6 +2930,11 @@ public:
void
set (std::auto_ptr&lt;X>);
+ // Detach and return the contained value.
+ //
+ std::auto_ptr&lt;X>
+ detach ();
+
void
reset ();
};
@@ -2968,6 +2996,9 @@ f (object&amp; o)
p = new string ("hello");
o.member ().set (p); // set, assumes ownership
+
+ p = o.member ().detach (); // detach, member is reset
+ o.member ().set (p); // re-attach
}
</pre>
@@ -3042,15 +3073,45 @@ public:
sequence interface as defined by the ISO/ANSI Standard for
C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences").
Practically, this means that you can treat such a sequence
- as if it was <code>std::vector</code>. One notable extension
- to the standard interface that is available only for
- sequences of non-fundamental C++ types is the addition of
+ as if it was <code>std::vector</code>. Two notable extensions
+ to the standard interface that are available only for
+ sequences of non-fundamental C++ types are the addition of
the overloaded <code>push_back</code> and <code>insert</code>
- member functions which instead of the constant reference
- to the element type accept automatic pointer to the element
- type. These functions assume ownership of the pointed to
- object and resets the passed automatic pointer.
- </p>
+ as well as the <code>detach_back</code> and <code>detach</code>
+ member functions. The additional <code>push_back</code> and
+ <code>insert</code> functions accept an automatic pointer to the
+ element type instead of the constant reference. They assume
+ ownership of the pointed to object and resets the passed
+ automatic pointer. The <code>detach_back</code> and
+ <code>detach</code> functions detach the element
+ value from the sequence container and, by default, remove
+ the element from the sequence. These additional functions
+ have the following signatures:</p>
+
+ <pre class="c++">
+template &lt;typename X>
+class sequence
+{
+public:
+ ...
+
+ void
+ push_back (std::auto_ptr&lt;X>)
+
+ iterator
+ insert (iterator position, std::auto_ptr&lt;X>)
+
+ std::auto_ptr&lt;X>
+ detach_back (bool pop = true);
+
+ iterator
+ detach (iterator position,
+ std::auto_ptr&lt;X>&amp; result,
+ bool erase = true)
+
+ ...
+}
+ </pre>
<p>The following code shows how one could use this mapping:</p>
@@ -3074,7 +3135,9 @@ f (object&amp; o)
s.push_back ("hello"); // deep copy
std::auto_ptr&lt;string> p (new string ("hello"));
- s.push_back (o); // assumes ownership
+ s.push_back (p); // assumes ownership
+ p = s.detach_back (); // detach and pop
+ s.push_back (p); // re-append
// Setting a new container.
//