From 36ba4a4f1af667682416f48c1698b1167e66e2b1 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 14 Oct 2010 16:13:36 +0200
Subject: Omit _present(bool) for variable-length members

---
 documentation/cxx/hybrid/guide/index.xhtml | 34 +++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

(limited to 'documentation')

diff --git a/documentation/cxx/hybrid/guide/index.xhtml b/documentation/cxx/hybrid/guide/index.xhtml
index ebb67fb..601574d 100644
--- a/documentation/cxx/hybrid/guide/index.xhtml
+++ b/documentation/cxx/hybrid/guide/index.xhtml
@@ -2267,8 +2267,8 @@ class person
   </pre>
 
   <p>Compared to the <em>one</em> cardinality class, <em>optional</em> adds
-     two extra functions for querying and modifying the element's presence
-     status. The following example shows how we can use these functions:</p>
+     functions for querying and modifying the member's presence status.
+     The following example shows how we can use these functions:</p>
 
   <pre class="c++">
 person&amp; p = ...
@@ -2280,6 +2280,33 @@ if (p.middle_name_present ())
 }
   </pre>
 
+  <p>If an optional member is of a variable-length type, then the second
+     <code>_present()</code> function is omitted. This is done to help
+     detect programming errors that result from a type becoming
+     variable-length due to schema changes. In this situation, before
+     the type becomes variable-length, calling the presence function
+     with <code>true</code> as its argument and then accessing the
+     member is valid. Once the type becomes variable-length, the
+     same sequence of calls would lead to a runtime error. By
+     omitting the second <code>_present()</code> function for
+     variable-length types, this kind of errors can be detected
+     at compile time. To reset an optional member of a variable-length
+     type you can call the member modifier function with <code>NULL</code>
+     as its argument. For example, if the <code>middle_name</code>
+     member was of a variable-length type, then the above code fragment
+     would look like this:</p>
+
+  <pre class="c++">
+person&amp; p = ...
+
+if (p.middle_name_present ())
+{
+  cout &lt;&lt; *p.middle_name () &lt;&lt; endl;
+  p.middle_name (0); // Reset to the "not present" state.
+}
+  </pre>
+
+
   <p>There are two cases in the <em>optional</em> cardinality class that
      are handled differently. These are optional attributes with default
      and fixed values. When an optional attribute declaration in XML Schema
@@ -3021,9 +3048,6 @@ public:
   bool
   sequence_present () const;
 
-  void
-  sequence_present (bool);
-
   const sequence_type&amp;
   sequence () const;
 
-- 
cgit v1.1