diff options
author | Boris Kolpackov <boris@codesynthesis.com> | 2009-04-02 12:22:38 +0200 |
---|---|---|
committer | Boris Kolpackov <boris@codesynthesis.com> | 2009-04-02 12:22:38 +0200 |
commit | 8336dd4c16d4885989a6d8f0c83a4b401f5cb63b (patch) | |
tree | 26ca613e7f3a3fe9fb75bf5bb3b65503661e0ebf /documentation | |
parent | e4c22d3686da0e973e21eae0561c1169c0eeff36 (diff) |
Add support for attributes with default and fixed values.
tests/cxx/hybrid/default: new test
tests/cxx/hybrid/binary: update to test default and fixed values
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/cxx/hybrid/guide/index.xhtml | 138 | ||||
-rw-r--r-- | documentation/xsde.1 | 4 | ||||
-rw-r--r-- | documentation/xsde.xhtml | 4 |
3 files changed, 145 insertions, 1 deletions
diff --git a/documentation/cxx/hybrid/guide/index.xhtml b/documentation/cxx/hybrid/guide/index.xhtml index 5871593..d497a14 100644 --- a/documentation/cxx/hybrid/guide/index.xhtml +++ b/documentation/cxx/hybrid/guide/index.xhtml @@ -2031,7 +2031,143 @@ if (p.middle_name_present ()) } </pre> - <p>Finally, the <em>sequence</em> cardinality class covers all elements + <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 + specifies a default or fixed value and such an attribute is not present + in the XML document, the attribute is assumed to have the default or + fixed value, respectively. Furthermore, if an attribute with the + fixed value is set in the XML document, then the attribute value + should be the same as its fixed value.</p> + + <p>For an optional attribute with a default value, the functions for + querying and modifying the attribute's presence status are replaced + with functions that allow you to determine whether the attribute has + the default value. The accessor functions can be called at any time + since an optional attribute with a default value always has some + value. Also an extra static function is provided to allow you to + obtain the default value. Consider the following modification to + the <code>person</code> type which adds the <code>verified</code> + attribute with the default value:</p> + + <pre class="xml"> +<xs:complexType name="person"> + <xs:sequence> + <xs:element name="first-name" type="xs:string"/> + ... + </xs:sequence> + <xs:attribute name="id" type="xs:unsignedInt" use="required"/> + <xs:attribute name="verified" type="xs:boolean" default="false"/> +</xs:complexType> + </pre> + + <p>The code fragment below shows the accessor and modifier functions + that are generated for this new attribute in the <code>person</code> + class:</p> + + <pre class="c++"> +class person +{ + // verified + // + bool + verified_default () const; + + void + verified_default (bool); + + bool + verified () const; + + bool& + verified (); + + void + verified (bool); + + static bool + verified_default_value (); +}; + </pre> + + <p>When we create an object of the <code>person</code> class, the + <code>verified</code> member is automatically initialized to the + default value. The following example shows how we can manipulate + the <code>verified</code> attribute value:</p> + + <pre class="c++"> +person p; // verified is set to the default value (false). + +if (p.verified_default ()) + p.verified (true); +else + p.verified_default (true); // Revert to the default value. + +bool v = p.verified (); // Ok, can always be called. +bool vd = person::verified_default_value (); + </pre> + + <p>Note that modifying an attribute of a variable-length type via + the reference when the attribute is set to the default value is + illegal since this will modify the default value shared by all + instances. For example:</p> + + <pre class="c++"> +type& x = ... + +if (x.foo_default ()) +{ + foo& f = x.foo (); // foo is variable-length, for example NMTOKENS + f.push_back ("aaa"); // Illegal. +} + +if (x.foo_default ()) +{ + foo* f = new foo; + f->push_back ("aaa"); + x.foo (f); // Ok. +} + </pre> + + <p>Because an attribute with a fixed value can only be set to that + value, only the read-only (constant) accessor and the static + function for obtaining the fixed value are provided for such + attributes. Similar to the default values, members with fixed + values of a newly created object are automatically initialized + to their respective fixed values. Consider the following + modification to the <code>verified</code> attribute from the + schema above:</p> + + <pre class="xml"> +<xs:complexType name="person"> + ... + <xs:attribute name="verified" type="xs:boolean" fixed="true"/> +</xs:complexType> + </pre> + + <p>The code fragment below shows the accessor functions that are + generated for this attribute in the <code>person</code> + class:</p> + + <pre class="c++"> +class person +{ + // verified + // + bool + verified () const; + + static bool + verified_fixed_value (); +}; + </pre> + + <p>During serialization, attributes that are set to default and fixed + values are explicitly specified in the resulting XML document. + You can use the <code>--omit-default-attributes</code> XSD/e + compiler option to omit such attributes from the serialized XML.</p> + + <p>The <em>sequence</em> cardinality class covers all elements that can occur more than once. In our example, the <code>person</code> element in the <code>people</code> type belongs to this cardinality class. The following code fragment shows diff --git a/documentation/xsde.1 b/documentation/xsde.1 index 62cc55d..874a4de 100644 --- a/documentation/xsde.1 +++ b/documentation/xsde.1 @@ -944,6 +944,10 @@ Suppress the generation of validation code in parser. .IP "\fB\--suppress-serializer-val\fR" Suppress the generation of validation code in serializer. +.IP "\fB\--omit-default-attributes\fR" +Omit attributes with default and fixed values from serialized XML +documents. + .IP "\fB\--generate-detach\fR" Generate detach functions for elements and attributes of variable-length types. These functions, for example, allow you to move sub-trees in the diff --git a/documentation/xsde.xhtml b/documentation/xsde.xhtml index c8f602a..697c751 100644 --- a/documentation/xsde.xhtml +++ b/documentation/xsde.xhtml @@ -816,6 +816,10 @@ <dt><code><b>--suppress-serializer-val</b></code></dt> <dd>Suppress the generation of validation code in serializer.</dd> + <dt><code><b>--omit-default-attributes</b></code></dt> + <dd>Omit attributes with default and fixed values from serialized + XML documents.</dd> + <dt><code><b>--generate-detach</b></code></dt> <dd>Generate detach functions for elements and attributes of variable-length types. These functions, for example, allow |