summaryrefslogtreecommitdiff
path: root/doc/cxx/tree/manual/index.xhtml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/cxx/tree/manual/index.xhtml')
-rw-r--r--doc/cxx/tree/manual/index.xhtml6822
1 files changed, 0 insertions, 6822 deletions
diff --git a/doc/cxx/tree/manual/index.xhtml b/doc/cxx/tree/manual/index.xhtml
deleted file mode 100644
index 550c07e..0000000
--- a/doc/cxx/tree/manual/index.xhtml
+++ /dev/null
@@ -1,6822 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
-
-<head>
- <title>C++/Tree Mapping User Manual</title>
-
- <meta name="copyright" content="&#169; 2009-2020 Code Synthesis Tools CC"/>
- <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,tree,serialization,guide,manual,examples"/>
- <meta name="description" content="C++/Tree Mapping User Manual"/>
- <meta name="revision" content="4.1.0"/>
-
- <link rel="stylesheet" type="text/css" href="../../../default.css" />
-
-<style type="text/css">
- pre {
- padding : 0 0 0 0em;
- margin : 0em 0em 0em 0;
-
- font-size : 102%
- }
-
- body {
- min-width: 48em;
- }
-
- h1 {
- font-weight: bold;
- font-size: 200%;
- }
-
- h2 {
- font-weight : bold;
- font-size : 150%;
-
- padding-top : 0.8em;
- }
-
- h3 {
- font-size : 130%;
- padding-top : 0.8em;
- }
-
- /* Adjust indentation for three levels. */
- #container {
- max-width: 48em;
- }
-
- #content {
- padding: 0 0.1em 0 4em;
- /*background-color: red;*/
- }
-
- #content h1 {
- margin-left: -2.06em;
- }
-
- #content h2 {
- margin-left: -1.33em;
- }
-
- /* Title page */
-
- #titlepage {
- padding: 2em 0 1em 0;
- border-bottom: 1px solid black;
- }
-
- #titlepage #title {
- font-weight: bold;
- font-size: 200%;
- text-align: center;
- padding: 1em 0 2em 0;
- }
-
- /* Lists */
- ul.list li {
- padding-top : 0.3em;
- padding-bottom : 0.3em;
- }
-
-
- /* Built-in table */
- #builtin {
- margin: 2em 0 2em 0;
-
- border-collapse : collapse;
- border : 1px solid;
- border-color : #000000;
-
- font-size : 11px;
- line-height : 14px;
- }
-
- #builtin th, #builtin td {
- border: 1px solid;
- padding : 0.9em 0.9em 0.7em 0.9em;
- }
-
- #builtin th {
- background : #cde8f6;
- }
-
- #builtin td {
- text-align: left;
- }
-
-
- /* default-fixed */
- #default-fixed {
- margin: 2em 0 2em 0;
-
- border-collapse : collapse;
- border : 1px solid;
- border-color : #000000;
-
- font-size : 11px;
- line-height : 14px;
- }
-
- #default-fixed th, #default-fixed td {
- border: 1px solid;
- padding : 0.9em 0.9em 0.7em 0.9em;
- }
-
- #default-fixed th {
- background : #cde8f6;
- }
-
- #default-fixed td {
- text-align: center;
- }
-
-
- /* */
- dl dt {
- padding : 0.8em 0 0 0;
- }
-
-
- /* TOC */
- table.toc {
- border-style : none;
- border-collapse : separate;
- border-spacing : 0;
-
- margin : 0.2em 0 0.2em 0;
- padding : 0 0 0 0;
- }
-
- table.toc tr {
- padding : 0 0 0 0;
- margin : 0 0 0 0;
- }
-
- table.toc * td, table.toc * th {
- border-style : none;
- margin : 0 0 0 0;
- vertical-align : top;
- }
-
- table.toc * th {
- font-weight : normal;
- padding : 0em 0.1em 0em 0;
- text-align : left;
- white-space : nowrap;
- }
-
- table.toc * table.toc th {
- padding-left : 1em;
- }
-
- table.toc * td {
- padding : 0em 0 0em 0.7em;
- text-align : left;
- }
-</style>
-
-
-</head>
-
-<body>
-<div id="container">
- <div id="content">
-
- <div class="noprint">
-
- <div id="titlepage">
- <div id="title">C++/Tree Mapping User Manual</div>
-
- <p>Copyright &#169; 2009-2020 Code Synthesis Tools CC.</p>
-
- <p>Permission is granted to copy, distribute and/or modify this
- document under the terms of the
- <a href="https://www.codesynthesis.com/licenses/fdl-1.2.txt">GNU Free
- Documentation License, version 1.2</a>; with no Invariant Sections,
- no Front-Cover Texts and no Back-Cover Texts.
- </p>
-
- <p>This document is available in the following formats:
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/index.xhtml">XHTML</a>,
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/cxx-tree-manual.pdf">PDF</a>, and
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/cxx-tree-manual.ps">PostScript</a>.</p>
- </div>
-
- <h1>Table of Contents</h1>
-
- <table class="toc">
- <tr>
- <th></th><td><a href="#0">Preface</a>
- <table class="toc">
- <tr><th></th><td><a href="#0.1">About This Document</a></td></tr>
- <tr><th></th><td><a href="#0.2">More Information</a></td></tr>
- </table>
- </td>
- </tr>
-
- <tr>
- <th>1</th><td><a href="#1">Introduction</a></td>
- </tr>
-
- <tr>
- <th>2</th><td><a href="#2">C++/Tree Mapping</a>
- <table class="toc">
- <tr>
- <th>2.1</th><td><a href="#2.1">Preliminary Information</a>
- <table class="toc">
- <tr><th>2.1.1</th><td><a href="#2.1.1">C++ Standard</a></td></tr>
- <tr><th>2.1.2</th><td><a href="#2.1.2">Identifiers</a></td></tr>
- <tr><th>2.1.3</th><td><a href="#2.1.3">Character Type and Encoding</a></td></tr>
- <tr><th>2.1.4</th><td><a href="#2.1.4">XML Schema Namespace</a></td></tr>
- <tr><th>2.1.5</th><td><a href="#2.1.5">Anonymous Types</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.2</th><td><a href="#2.2">Error Handling</a>
- <table class="toc">
- <tr><th>2.2.1</th><td><a href="#2.2.1"><code>xml_schema::duplicate_id</code></a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.3</th><td><a href="#2.3">Mapping for <code>import</code> and <code>include</code></a>
- <table class="toc">
- <tr><th>2.3.1</th><td><a href="#2.3.1">Import</a></td></tr>
- <tr><th>2.3.2</th><td><a href="#2.3.2">Inclusion with Target Namespace</a></td></tr>
- <tr><th>2.3.3</th><td><a href="#2.3.3">Inclusion without Target Namespace</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.4</th><td><a href="#2.4">Mapping for Namespaces</a></td>
- </tr>
- <tr>
- <th>2.5</th><td><a href="#2.5">Mapping for Built-in Data Types</a>
- <table class="toc">
- <tr><th>2.5.1</th><td><a href="#2.5.1">Inheritance from Built-in Data Types</a></td></tr>
- <tr><th>2.5.2</th><td><a href="#2.5.2">Mapping for <code>anyType</code></a></td></tr>
- <tr><th>2.5.3</th><td><a href="#2.5.3">Mapping for <code>anySimpleType</code></a></td></tr>
- <tr><th>2.5.4</th><td><a href="#2.5.4">Mapping for <code>QName</code></a></td></tr>
- <tr><th>2.5.5</th><td><a href="#2.5.5">Mapping for <code>IDREF</code></a></td></tr>
- <tr><th>2.5.6</th><td><a href="#2.5.6">Mapping for <code>base64Binary</code> and <code>hexBinary</code></a></td></tr>
- <tr><th>2.5.7</th><td><a href="#2.5.7">Time Zone Representation</a></td></tr>
- <tr><th>2.5.8</th><td><a href="#2.5.8">Mapping for <code>date</code></a></td></tr>
- <tr><th>2.5.9</th><td><a href="#2.5.9">Mapping for <code>dateTime</code></a></td></tr>
- <tr><th>2.5.10</th><td><a href="#2.5.10">Mapping for <code>duration</code></a></td></tr>
- <tr><th>2.5.11</th><td><a href="#2.5.11">Mapping for <code>gDay</code></a></td></tr>
- <tr><th>2.5.12</th><td><a href="#2.5.12">Mapping for <code>gMonth</code></a></td></tr>
- <tr><th>2.5.13</th><td><a href="#2.5.13">Mapping for <code>gMonthDay</code></a></td></tr>
- <tr><th>2.5.14</th><td><a href="#2.5.14">Mapping for <code>gYear</code></a></td></tr>
- <tr><th>2.5.15</th><td><a href="#2.5.15">Mapping for <code>gYearMonth</code></a></td></tr>
- <tr><th>2.5.16</th><td><a href="#2.5.16">Mapping for <code>time</code></a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.6</th><td><a href="#2.6">Mapping for Simple Types</a>
- <table class="toc">
- <tr><th>2.6.1</th><td><a href="#2.6.1">Mapping for Derivation by Restriction</a></td></tr>
- <tr><th>2.6.2</th><td><a href="#2.6.2">Mapping for Enumerations</a></td></tr>
- <tr><th>2.6.3</th><td><a href="#2.6.3">Mapping for Derivation by List</a></td></tr>
- <tr><th>2.6.4</th><td><a href="#2.6.4">Mapping for Derivation by Union</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.7</th><td><a href="#2.7">Mapping for Complex Types</a>
- <table class="toc">
- <tr><th>2.7.1</th><td><a href="#2.7.1">Mapping for Derivation by Extension</a></td></tr>
- <tr><th>2.7.2</th><td><a href="#2.7.2">Mapping for Derivation by Restriction</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.8</th><td><a href="#2.8">Mapping for Local Elements and Attributes</a>
- <table class="toc">
- <tr><th>2.8.1</th><td><a href="#2.8.1">Mapping for Members with the One Cardinality Class</a></td></tr>
- <tr><th>2.8.2</th><td><a href="#2.8.2">Mapping for Members with the Optional Cardinality Class</a></td></tr>
- <tr><th>2.8.3</th><td><a href="#2.8.3">Mapping for Members with the Sequence Cardinality Class</a></td></tr>
- <tr><th>2.8.4</th><td><a href="#2.8.4">Element Order</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.9</th><td><a href="#2.9">Mapping for Global Elements</a>
- <table class="toc">
- <tr><th>2.9.1</th><td><a href="#2.9.1">Element Types</a></td></tr>
- <tr><th>2.9.2</th><td><a href="#2.9.2">Element Map</a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.10</th><td><a href="#2.10">Mapping for Global Attributes</a></td>
- </tr>
- <tr>
- <th>2.11</th><td><a href="#2.11">Mapping for <code>xsi:type</code> and Substitution Groups</a></td>
- </tr>
- <tr>
- <th>2.12</th><td><a href="#2.12">Mapping for <code>any</code> and <code>anyAttribute</code></a>
- <table class="toc">
- <tr><th>2.12.1</th><td><a href="#2.12.1">Mapping for <code>any</code> with the One Cardinality Class</a></td></tr>
- <tr><th>2.12.2</th><td><a href="#2.12.2">Mapping for <code>any</code> with the Optional Cardinality Class</a></td></tr>
- <tr><th>2.12.3</th><td><a href="#2.12.3">Mapping for <code>any</code> with the Sequence Cardinality Class</a></td></tr>
- <tr><th>2.12.4</th><td><a href="#2.12.4">Element Wildcard Order</a></td></tr>
- <tr><th>2.12.5</th><td><a href="#2.12.5">Mapping for <code>anyAttribute</code></a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>2.13</th><td><a href="#2.13">Mapping for Mixed Content Models</a></td>
- </tr>
- </table>
- </td>
- </tr>
-
- <tr>
- <th>3</th><td><a href="#3">Parsing</a>
- <table class="toc">
- <tr>
- <th>3.1</th><td><a href="#3.1">Initializing the Xerces-C++ Runtime</a></td>
- </tr>
- <tr>
- <th>3.2</th><td><a href="#3.2">Flags and Properties</a></td>
- </tr>
- <tr>
- <th>3.3</th><td><a href="#3.3">Error Handling</a>
- <table class="toc">
- <tr><th>3.3.1</th><td><a href="#3.3.1"><code>xml_schema::parsing</code></a></td></tr>
- <tr><th>3.3.2</th><td><a href="#3.3.2"><code>xml_schema::expected_element</code></a></td></tr>
- <tr><th>3.3.3</th><td><a href="#3.3.3"><code>xml_schema::unexpected_element</code></a></td></tr>
- <tr><th>3.3.4</th><td><a href="#3.3.4"><code>xml_schema::expected_attribute</code></a></td></tr>
- <tr><th>3.3.5</th><td><a href="#3.3.5"><code>xml_schema::unexpected_enumerator</code></a></td></tr>
- <tr><th>3.3.6</th><td><a href="#3.3.6"><code>xml_schema::expected_text_content</code></a></td></tr>
- <tr><th>3.3.7</th><td><a href="#3.3.7"><code>xml_schema::no_type_info</code></a></td></tr>
- <tr><th>3.3.8</th><td><a href="#3.3.8"><code>xml_schema::not_derived</code></a></td></tr>
- <tr><th>3.3.9</th><td><a href="#3.3.9"><code>xml_schema::not_prefix_mapping</code></a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>3.4</th><td><a href="#3.4">Reading from a Local File or URI</a></td>
- </tr>
- <tr>
- <th>3.5</th><td><a href="#3.5">Reading from <code>std::istream</code></a></td>
- </tr>
- <tr>
- <th>3.6</th><td><a href="#3.6">Reading from <code>xercesc::InputSource</code></a></td>
- </tr>
- <tr>
- <th>3.7</th><td><a href="#3.7">Reading from DOM</a></td>
- </tr>
- </table>
- </td>
- </tr>
-
- <tr>
- <th>4</th><td><a href="#4">Serialization</a>
- <table class="toc">
- <tr>
- <th>4.1</th><td><a href="#4.1">Initializing the Xerces-C++ Runtime</a></td>
- </tr>
- <tr>
- <th>4.2</th><td><a href="#4.2">Namespace Infomap and Character Encoding</a></td>
- </tr>
- <tr>
- <th>4.3</th><td><a href="#4.3">Flags</a></td>
- </tr>
- <tr>
- <th>4.4</th><td><a href="#4.4">Error Handling</a>
- <table class="toc">
- <tr><th>4.4.1</th><td><a href="#4.4.1"><code>xml_schema::serialization</code></a></td></tr>
- <tr><th>4.4.2</th><td><a href="#4.4.2"><code>xml_schema::unexpected_element</code></a></td></tr>
- <tr><th>4.4.3</th><td><a href="#4.4.3"><code>xml_schema::no_type_info</code></a></td></tr>
- </table>
- </td>
- </tr>
- <tr>
- <th>4.5</th><td><a href="#4.5">Serializing to <code>std::ostream</code></a></td>
- </tr>
- <tr>
- <th>4.6</th><td><a href="#4.6">Serializing to <code>xercesc::XMLFormatTarget</code></a></td>
- </tr>
- <tr>
- <th>4.7</th><td><a href="#4.7">Serializing to DOM</a></td>
- </tr>
- </table>
- </td>
- </tr>
-
- <tr>
- <th>5</th><td><a href="#5">Additional Functionality</a>
- <table class="toc">
- <tr>
- <th>5.1</th><td><a href="#5.1">DOM Association</a></td>
- </tr>
- <tr>
- <th>5.2</th><td><a href="#5.2">Binary Serialization</a></td>
- </tr>
- </table>
- </td>
- </tr>
-
- <tr>
- <th></th><td><a href="#A">Appendix A &mdash; Default and Fixed Values</a></td>
- </tr>
-
- </table>
- </div>
-
- <h1><a name="0">Preface</a></h1>
-
- <h2><a name="0.1">About This Document</a></h2>
-
- <p>This document describes the mapping of W3C XML Schema
- to the C++ programming language as implemented by
- <a href="https://www.codesynthesis.com/products/xsd">CodeSynthesis
- XSD</a> - an XML Schema to C++ data binding compiler. The mapping
- represents information stored in XML instance documents as a
- statically-typed, tree-like in-memory data structure and is
- called C++/Tree.
- </p>
-
- <p>Revision 4.1.0<br/> <!-- Remember to change revision in other places -->
- This revision of the manual describes the C++/Tree
- mapping as implemented by CodeSynthesis XSD version 4.1.0.
- </p>
-
- <p>This document is available in the following formats:
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/index.xhtml">XHTML</a>,
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/cxx-tree-manual.pdf">PDF</a>, and
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/cxx-tree-manual.ps">PostScript</a>.</p>
-
- <h2><a name="0.2">More Information</a></h2>
-
- <p>Beyond this manual, you may also find the following sources of
- information useful:</p>
-
- <ul class="list">
- <li><a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/">C++/Tree
- Mapping Getting Started Guide</a></li>
-
- <li><a href="http://wiki.codesynthesis.com/Tree/Customization_guide">C++/Tree
- Mapping Customization Guide</a></li>
-
- <li><a href="http://wiki.codesynthesis.com/Tree/FAQ">C++/Tree
- Mapping Frequently Asked Questions (FAQ)</a></li>
-
- <li><a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a></li>
-
- <li>The <code>examples/cxx/tree/</code> directory in the XSD
- distribution contains a collection of examples and a README
- file with an overview of each example.</li>
-
- <li>The <code>README</code> file in the XSD distribution explains
- how to compile the examples on various platforms.</li>
-
- <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a>
- mailing list is a place to ask questions. Furthermore the
- <a href="https://www.codesynthesis.com/pipermail/xsd-users/">archives</a>
- may already have answers to some of your questions.</li>
- </ul>
-
-
- <h1><a name="1">1 Introduction</a></h1>
-
- <p>C++/Tree is a W3C XML Schema to C++ mapping that represents the
- data stored in XML as a statically-typed, vocabulary-specific
- object model. Based on a formal description of an XML vocabulary
- (schema), the C++/Tree mapping produces a tree-like data structure
- suitable for in-memory processing as well as XML parsing and
- serialization code.</p>
-
- <p>A typical application that processes XML documents usually
- performs the following three steps: it first reads (parses) an XML
- instance document to an object model, it then performs
- some useful computations on that model which may involve
- modification of the model, and finally it may write (serialize)
- the modified object model back to XML.
- </p>
-
- <p>The C++/Tree mapping consists of C++ types that represent the
- given vocabulary (<a href="#2">Chapter 2, "C++/Tree Mapping"</a>),
- a set of parsing functions that convert XML documents to
- a tree-like in-memory data structure (<a href="#3">Chapter 3,
- "Parsing"</a>), and a set of serialization functions that convert
- the object model back to XML (<a href="#4">Chapter 4,
- "Serialization"</a>). Furthermore, the mapping provides a number
- of additional features, such as DOM association and binary
- serialization, that can be useful in some applications
- (<a href="#5">Chapter 5, "Additional Functionality"</a>).
- </p>
-
-
- <!-- Chapter 2 -->
-
-
- <h1><a name="2">2 C++/Tree Mapping</a></h1>
-
- <h2><a name="2.1">2.1 Preliminary Information</a></h2>
-
- <h3><a name="2.1.1">2.1.1 C++ Standard</a></h3>
-
- <p>The C++/Tree mapping provides support for ISO/IEC C++ 1998/2003 (C++98)
- and ISO/IEC C++ 2011 (C++11). To select the C++ standard for the
- generated code we use the <code>--std</code> XSD compiler command
- line option. While the majority of the examples in this manual use
- C++98, support for the new functionality and library components
- introduced in C++11 are discussed throughout the document.</p>
-
- <h3><a name="2.1.2">2.1.2 Identifiers</a></h3>
-
- <p>XML Schema names may happen to be reserved C++ keywords or contain
- characters that are illegal in C++ identifiers. To avoid C++ compilation
- problems, such names are changed (escaped) when mapped to C++. If an
- XML Schema name is a C++ keyword, the "_" suffix is added to it. All
- character of an XML Schema name that are not allowed in C++ identifiers
- are replaced with "_".
- </p>
-
- <p>For example, XML Schema name <code>try</code> will be mapped to
- C++ identifier <code>try_</code>. Similarly, XML Schema name
- <code>strange.na-me</code> will be mapped to C++ identifier
- <code>strange_na_me</code>.
- </p>
-
- <p>Furthermore, conflicts between type names and function names in the
- same scope are resolved using name escaping. Such conflicts include
- both a global element (which is mapped to a set of parsing and/or
- serialization functions or element types, see <a href="#2.9">Section
- 2.9, "Mapping for Global Elements"</a>) and a global type sharing the
- same name as well as a local element or attribute inside a type having
- the same name as the type itself.</p>
-
- <p>For example, if we had a global type <code>catalog</code>
- and a global element with the same name then the type would be
- mapped to a C++ class with name <code>catalog</code> while the
- parsing functions corresponding to the global element would have
- their names escaped as <code>catalog_</code>.
- </p>
-
- <p>By default the mapping uses the so-called K&amp;R (Kernighan and
- Ritchie) identifier naming convention which is also used throughout
- this manual. In this convention both type and function names are in
- lower case and words are separated by underscores. If your application
- code or schemas use a different notation, you may want to change the
- naming convention used by the mapping for consistency.
- The compiler supports a set of widely-used naming conventions
- that you can select with the <code>--type-naming</code> and
- <code>--function-naming</code> options. You can also further
- refine one of the predefined conventions or create a completely
- custom naming scheme by using the <code>--*-regex</code> options.
- For more detailed information on these options refer to the NAMING
- CONVENTION section in the <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a>.</p>
-
- <h3><a name="2.1.3">2.1.3 Character Type and Encoding</a></h3>
-
- <p>The code that implements the mapping, depending on the
- <code>--char-type</code> option, is generated using either
- <code>char</code> or <code>wchar_t</code> as the character
- type. In this document code samples use symbol <code>C</code>
- to refer to the character type you have selected when translating
- your schemas, for example <code>std::basic_string&lt;C></code>.
- </p>
-
- <p>Another aspect of the mapping that depends on the character type
- is character encoding. For the <code>char</code> character type
- the default encoding is UTF-8. Other supported encodings are
- ISO-8859-1, Xerces-C++ Local Code Page (LPC), as well as
- custom encodings and can be selected with the
- <code>--char-encoding</code> command line option.</p>
-
- <p>For the <code>wchar_t</code> character type the encoding is
- automatically selected between UTF-16 and UTF-32/UCS-4 depending
- on the size of the <code>wchar_t</code> type. On some platforms
- (for example, Windows with Visual C++ and AIX with IBM XL C++)
- <code>wchar_t</code> is 2 bytes long. For these platforms the
- encoding is UTF-16. On other platforms <code>wchar_t</code> is 4 bytes
- long and UTF-32/UCS-4 is used.</p>
-
- <h3><a name="2.1.4">2.1.4 XML Schema Namespace</a></h3>
-
- <p>The mapping relies on some predefined types, classes, and functions
- that are logically defined in the XML Schema namespace reserved for
- the XML Schema language (<code>http://www.w3.org/2001/XMLSchema</code>).
- By default, this namespace is mapped to C++ namespace
- <code>xml_schema</code>. It is automatically accessible
- from a C++ compilation unit that includes a header file generated
- from an XML Schema definition.
- </p>
-
- <p>Note that, if desired, the default mapping of this namespace can be
- changed as described in <a href="#2.4">Section 2.4, "Mapping for
- Namespaces"</a>.
- </p>
-
-
- <h3><a name="2.1.5">2.1.5 Anonymous Types</a></h3>
-
- <p>For the purpose of code generation, anonymous types defined in
- XML Schema are automatically assigned names that are derived
- from enclosing attributes and elements. Otherwise, such types
- follows standard mapping rules for simple and complex type
- definitions (see <a href="#2.6">Section 2.6, "Mapping for Simple Types"</a>
- and <a href="#2.7">Section 2.7, "Mapping for Complex Types"</a>).
- For example, in the following schema fragment:
- </p>
-
- <pre class="xml">
-&lt;element name="object">
- &lt;complexType>
- ...
- &lt;/complexType>
-&lt;/element>
- </pre>
-
- <p>The anonymous type defined inside element <code>object</code> will
- be given name <code>object</code>. The compiler has a number of
- options that control the process of anonymous type naming. For more
- information refer to the <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a>.</p>
-
-
- <h2><a name="2.2">2.2 Error Handling</a></h2>
-
- <p>The mapping uses the C++ exception handling mechanism as a primary way
- of reporting error conditions. All exceptions that are specified in
- this mapping derive from <code>xml_schema::exception</code> which
- itself is derived from <code>std::exception</code>:
- </p>
-
- <pre class="c++">
-struct exception: virtual std::exception
-{
- friend
- std::basic_ostream&lt;C>&amp;
- operator&lt;&lt; (std::basic_ostream&lt;C>&amp; os, const exception&amp; e)
- {
- e.print (os);
- return os;
- }
-
-protected:
- virtual void
- print (std::basic_ostream&lt;C>&amp;) const = 0;
-};
- </pre>
-
- <p>The exception hierarchy supports "virtual" <code>operator&lt;&lt;</code>
- which allows you to obtain diagnostics corresponding to the thrown
- exception using the base exception interface. For example:</p>
-
- <pre class="c++">
-try
-{
- ...
-}
-catch (const xml_schema::exception&amp; e)
-{
- cerr &lt;&lt; e &lt;&lt; endl;
-}
- </pre>
-
- <p>The following sub-sections describe exceptions thrown by the
- types that constitute the object model.
- <a href="#3.3">Section 3.3, "Error Handling"</a> of
- <a href="#3">Chapter 3, "Parsing"</a> describes exceptions
- and error handling mechanisms specific to the parsing functions.
- <a href="#4.4">Section 4.4, "Error Handling"</a> of
- <a href="#4">Chapter 4, "Serialization"</a> describes exceptions
- and error handling mechanisms specific to the serialization functions.
- </p>
-
-
- <h3><a name="2.2.1">2.2.1 <code>xml_schema::duplicate_id</code></a></h3>
-
- <pre class="c++">
-struct duplicate_id: virtual exception
-{
- duplicate_id (const std::basic_string&lt;C>&amp; id);
-
- const std::basic_string&lt;C>&amp;
- id () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::duplicate_id</code> is thrown when
- a conflicting instance of <code>xml_schema::id</code> (see
- <a href="#2.5">Section 2.5, "Mapping for Built-in Data Types"</a>)
- is added to a tree. The offending ID value can be obtained using
- the <code>id</code> function.
- </p>
-
- <h2><a name="2.3">2.3 Mapping for <code>import</code> and <code>include</code></a></h2>
-
- <h3><a name="2.3.1">2.3.1 Import</a></h3>
-
- <p>The XML Schema <code>import</code> element is mapped to the C++
- Preprocessor <code>#include</code> directive. The value of
- the <code>schemaLocation</code> attribute is used to derive
- the name of the header file that appears in the <code>#include</code>
- directive. For instance:
- </p>
-
- <pre class="xml">
-&lt;import namespace="https://www.codesynthesis.com/test"
- schemaLocation="test.xsd"/>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-#include "test.hxx"
- </pre>
-
- <p>Note that you will need to compile imported schemas separately
- in order to produce corresponding header files.</p>
-
- <h3><a name="2.3.2">2.3.2 Inclusion with Target Namespace</a></h3>
-
- <p>The XML Schema <code>include</code> element which refers to a schema
- with a target namespace or appears in a schema without a target namespace
- follows the same mapping rules as the <code>import</code> element,
- see <a href="#2.3.1">Section 2.3.1, "Import"</a>.
- </p>
-
- <h3><a name="2.3.3">2.3.3 Inclusion without Target Namespace</a></h3>
-
- <p>For the XML Schema <code>include</code> element which refers to a schema
- without a target namespace and appears in a schema with a target
- namespace (such inclusion sometimes called "chameleon inclusion"),
- declarations and definitions from the included schema are generated
- in-line in the namespace of the including schema as if they were
- declared and defined there verbatim. For example, consider the
- following two schemas:
- </p>
-
- <pre class="xml">
-&lt;-- common.xsd -->
-&lt;schema>
- &lt;complexType name="type">
- ...
- &lt;/complexType>
-&lt;/schema>
-
-&lt;-- test.xsd -->
-&lt;schema targetNamespace="https://www.codesynthesis.com/test">
- &lt;include schemaLocation="common.xsd"/>
-&lt;/schema>
- </pre>
-
- <p>The fragment of interest from the generated header file for
- <code>text.xsd</code> would look like this:</p>
-
- <pre class="c++">
-// test.hxx
-namespace test
-{
- class type
- {
- ...
- };
-}
- </pre>
-
- <h2><a name="2.4">2.4 Mapping for Namespaces</a></h2>
-
- <p>An XML Schema namespace is mapped to one or more nested C++
- namespaces. XML Schema namespaces are identified by URIs.
- By default, a namespace URI is mapped to a sequence of
- C++ namespace names by removing the protocol and host parts
- and splitting the rest into a sequence of names with '<code>/</code>'
- as the name separator. For instance:
- </p>
-
- <pre class="xml">
-&lt;schema targetNamespace="https://www.codesynthesis.com/system/test">
- ...
-&lt;/schema>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-namespace system
-{
- namespace test
- {
- ...
- }
-}
- </pre>
-
- <p>The default mapping of namespace URIs to C++ namespace names can be
- altered using the <code>--namespace-map</code> and
- <code>--namespace-regex</code> options. See the
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a> for more information.
- </p>
-
- <h2><a name="2.5">2.5 Mapping for Built-in Data Types</a></h2>
-
- <p>The mapping of XML Schema built-in data types to C++ types is
- summarized in the table below.</p>
-
- <!-- border="1" is necessary for html2ps -->
- <table id="builtin" border="1">
- <tr>
- <th>XML Schema type</th>
- <th>Alias in the <code>xml_schema</code> namespace</th>
- <th>C++ type</th>
- </tr>
-
- <tr>
- <th colspan="3">anyType and anySimpleType types</th>
- </tr>
- <tr>
- <td><code>anyType</code></td>
- <td><code>type</code></td>
- <td><a href="#2.5.2">Section 2.5.2, "Mapping for <code>anyType</code>"</a></td>
- </tr>
- <tr>
- <td><code>anySimpleType</code></td>
- <td><code>simple_type</code></td>
- <td><a href="#2.5.3">Section 2.5.3, "Mapping for <code>anySimpleType</code>"</a></td>
- </tr>
-
- <tr>
- <th colspan="3">fixed-length integral types</th>
- </tr>
- <!-- 8-bit -->
- <tr>
- <td><code>byte</code></td>
- <td><code>byte</code></td>
- <td><code>signed&nbsp;char</code></td>
- </tr>
- <tr>
- <td><code>unsignedByte</code></td>
- <td><code>unsigned_byte</code></td>
- <td><code>unsigned&nbsp;char</code></td>
- </tr>
-
- <!-- 16-bit -->
- <tr>
- <td><code>short</code></td>
- <td><code>short_</code></td>
- <td><code>short</code></td>
- </tr>
- <tr>
- <td><code>unsignedShort</code></td>
- <td><code>unsigned_short</code></td>
- <td><code>unsigned&nbsp;short</code></td>
- </tr>
-
- <!-- 32-bit -->
- <tr>
- <td><code>int</code></td>
- <td><code>int_</code></td>
- <td><code>int</code></td>
- </tr>
- <tr>
- <td><code>unsignedInt</code></td>
- <td><code>unsigned_int</code></td>
- <td><code>unsigned&nbsp;int</code></td>
- </tr>
-
- <!-- 64-bit -->
- <tr>
- <td><code>long</code></td>
- <td><code>long_</code></td>
- <td><code>long&nbsp;long</code></td>
- </tr>
- <tr>
- <td><code>unsignedLong</code></td>
- <td><code>unsigned_long</code></td>
- <td><code>unsigned&nbsp;long&nbsp;long</code></td>
- </tr>
-
- <tr>
- <th colspan="3">arbitrary-length integral types</th>
- </tr>
- <tr>
- <td><code>integer</code></td>
- <td><code>integer</code></td>
- <td><code>long&nbsp;long</code></td>
- </tr>
- <tr>
- <td><code>nonPositiveInteger</code></td>
- <td><code>non_positive_integer</code></td>
- <td><code>long&nbsp;long</code></td>
- </tr>
- <tr>
- <td><code>nonNegativeInteger</code></td>
- <td><code>non_negative_integer</code></td>
- <td><code>unsigned long&nbsp;long</code></td>
- </tr>
- <tr>
- <td><code>positiveInteger</code></td>
- <td><code>positive_integer</code></td>
- <td><code>unsigned long&nbsp;long</code></td>
- </tr>
- <tr>
- <td><code>negativeInteger</code></td>
- <td><code>negative_integer</code></td>
- <td><code>long&nbsp;long</code></td>
- </tr>
-
- <tr>
- <th colspan="3">boolean types</th>
- </tr>
- <tr>
- <td><code>boolean</code></td>
- <td><code>boolean</code></td>
- <td><code>bool</code></td>
- </tr>
-
- <tr>
- <th colspan="3">fixed-precision floating-point types</th>
- </tr>
- <tr>
- <td><code>float</code></td>
- <td><code>float_</code></td>
- <td><code>float</code></td>
- </tr>
- <tr>
- <td><code>double</code></td>
- <td><code>double_</code></td>
- <td><code>double</code></td>
- </tr>
-
- <tr>
- <th colspan="3">arbitrary-precision floating-point types</th>
- </tr>
- <tr>
- <td><code>decimal</code></td>
- <td><code>decimal</code></td>
- <td><code>double</code></td>
- </tr>
-
- <tr>
- <th colspan="3">string types</th>
- </tr>
- <tr>
- <td><code>string</code></td>
- <td><code>string</code></td>
- <td>type derived from <code>std::basic_string</code></td>
- </tr>
- <tr>
- <td><code>normalizedString</code></td>
- <td><code>normalized_string</code></td>
- <td>type derived from <code>string</code></td>
- </tr>
- <tr>
- <td><code>token</code></td>
- <td><code>token</code></td>
- <td>type&nbsp;derived&nbsp;from&nbsp;<code>normalized_string</code></td>
- </tr>
- <tr>
- <td><code>Name</code></td>
- <td><code>name</code></td>
- <td>type derived from <code>token</code></td>
- </tr>
- <tr>
- <td><code>NMTOKEN</code></td>
- <td><code>nmtoken</code></td>
- <td>type derived from <code>token</code></td>
- </tr>
- <tr>
- <td><code>NMTOKENS</code></td>
- <td><code>nmtokens</code></td>
- <td>type derived from <code>sequence&lt;nmtoken></code></td>
- </tr>
- <tr>
- <td><code>NCName</code></td>
- <td><code>ncname</code></td>
- <td>type derived from <code>name</code></td>
- </tr>
- <tr>
- <td><code>language</code></td>
- <td><code>language</code></td>
- <td>type derived from <code>token</code></td>
- </tr>
-
- <tr>
- <th colspan="3">qualified name</th>
- </tr>
- <tr>
- <td><code>QName</code></td>
- <td><code>qname</code></td>
- <td><a href="#2.5.4">Section 2.5.4, "Mapping for <code>QName</code>"</a></td>
- </tr>
-
- <tr>
- <th colspan="3">ID/IDREF types</th>
- </tr>
- <tr>
- <td><code>ID</code></td>
- <td><code>id</code></td>
- <td>type derived from <code>ncname</code></td>
- </tr>
- <tr>
- <td><code>IDREF</code></td>
- <td><code>idref</code></td>
- <td><a href="#2.5.5">Section 2.5.5, "Mapping for <code>IDREF</code>"</a></td>
- </tr>
- <tr>
- <td><code>IDREFS</code></td>
- <td><code>idrefs</code></td>
- <td>type derived from <code>sequence&lt;idref></code></td>
- </tr>
-
- <tr>
- <th colspan="3">URI types</th>
- </tr>
- <tr>
- <td><code>anyURI</code></td>
- <td><code>uri</code></td>
- <td>type derived from <code>std::basic_string</code></td>
- </tr>
-
- <tr>
- <th colspan="3">binary types</th>
- </tr>
- <tr>
- <td><code>base64Binary</code></td>
- <td><code>base64_binary</code></td>
- <td rowspan="2"><a href="#2.5.6">Section 2.5.6, "Mapping for
- <code>base64Binary</code> and <code>hexBinary</code>"</a></td>
- </tr>
- <tr>
- <td><code>hexBinary</code></td>
- <td><code>hex_binary</code></td>
- </tr>
-
- <tr>
- <th colspan="3">date/time types</th>
- </tr>
- <tr>
- <td><code>date</code></td>
- <td><code>date</code></td>
- <td><a href="#2.5.8">Section 2.5.8, "Mapping for
- <code>date</code>"</a></td>
- </tr>
- <tr>
- <td><code>dateTime</code></td>
- <td><code>date_time</code></td>
- <td><a href="#2.5.9">Section 2.5.9, "Mapping for
- <code>dateTime</code>"</a></td>
- </tr>
- <tr>
- <td><code>duration</code></td>
- <td><code>duration</code></td>
- <td><a href="#2.5.10">Section 2.5.10, "Mapping for
- <code>duration</code>"</a></td>
- </tr>
- <tr>
- <td><code>gDay</code></td>
- <td><code>gday</code></td>
- <td><a href="#2.5.11">Section 2.5.11, "Mapping for
- <code>gDay</code>"</a></td>
- </tr>
- <tr>
- <td><code>gMonth</code></td>
- <td><code>gmonth</code></td>
- <td><a href="#2.5.12">Section 2.5.12, "Mapping for
- <code>gMonth</code>"</a></td>
- </tr>
- <tr>
- <td><code>gMonthDay</code></td>
- <td><code>gmonth_day</code></td>
- <td><a href="#2.5.13">Section 2.5.13, "Mapping for
- <code>gMonthDay</code>"</a></td>
- </tr>
- <tr>
- <td><code>gYear</code></td>
- <td><code>gyear</code></td>
- <td><a href="#2.5.14">Section 2.5.14, "Mapping for
- <code>gYear</code>"</a></td>
- </tr>
- <tr>
- <td><code>gYearMonth</code></td>
- <td><code>gyear_month</code></td>
- <td><a href="#2.5.15">Section 2.5.15, "Mapping for
- <code>gYearMonth</code>"</a></td>
- </tr>
- <tr>
- <td><code>time</code></td>
- <td><code>time</code></td>
- <td><a href="#2.5.16">Section 2.5.16, "Mapping for
- <code>time</code>"</a></td>
- </tr>
-
- <tr>
- <th colspan="3">entity types</th>
- </tr>
- <tr>
- <td><code>ENTITY</code></td>
- <td><code>entity</code></td>
- <td>type derived from <code>name</code></td>
- </tr>
- <tr>
- <td><code>ENTITIES</code></td>
- <td><code>entities</code></td>
- <td>type derived from <code>sequence&lt;entity></code></td>
- </tr>
- </table>
-
- <p>All XML Schema built-in types are mapped to C++ classes that are
- derived from the <code>xml_schema::simple_type</code> class except
- where the mapping is to a fundamental C++ type.</p>
-
- <p>The <code>sequence</code> class template is defined in an
- implementation-specific namespace. It conforms to the
- 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
- 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 (<code>std::auto_ptr</code>
- or <code>std::unique_ptr</code>, depending on the C++ standard
- selected) to the element type. These functions assume ownership
- of the pointed to object and reset the passed automatic pointer.
- </p>
-
- <h3><a name="2.5.1">2.5.1 Inheritance from Built-in Data Types</a></h3>
-
- <p>In cases where the mapping calls for an inheritance from a built-in
- type which is mapped to a fundamental C++ type, a proxy type is
- used instead of the fundamental C++ type (C++ does not allow
- inheritance from fundamental types). For instance:</p>
-
- <pre class="xml">
-&lt;simpleType name="my_int">
- &lt;restriction base="int"/>
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class my_int: public fundamental_base&lt;int>
-{
- ...
-};
- </pre>
-
- <p>The <code>fundamental_base</code> class template provides a close
- emulation (though not exact) of a fundamental C++ type.
- It is defined in an implementation-specific namespace and has the
- following interface:</p>
-
- <pre class="c++">
-template &lt;typename X>
-class fundamental_base: public simple_type
-{
-public:
- fundamental_base ();
- fundamental_base (X)
- fundamental_base (const fundamental_base&amp;)
-
-public:
- fundamental_base&amp;
- operator= (const X&amp;);
-
-public:
- operator const X &amp; () const;
- operator X&amp; ();
-
- template &lt;typename Y>
- operator Y () const;
-
- template &lt;typename Y>
- operator Y ();
-};
- </pre>
-
- <h3><a name="2.5.2">2.5.2 Mapping for <code>anyType</code></a></h3>
-
- <p>The XML Schema <code>anyType</code> built-in data type is mapped to the
- <code>xml_schema::type</code> C++ class:</p>
-
- <pre class="c++">
-class type
-{
-public:
- virtual
- ~type ();
-
- type ();
- type (const type&amp;);
-
- type&amp;
- operator= (const type&amp;);
-
- virtual type*
- _clone () const;
-
- // anyType DOM content.
- //
-public:
- typedef element_optional dom_content_optional;
-
- const dom_content_optional&amp;
- dom_content () const;
-
- dom_content_optional&amp;
- dom_content ();
-
- void
- dom_content (const xercesc::DOMElement&amp;);
-
- void
- dom_content (xercesc::DOMElement*);
-
- void
- dom_content (const dom_content_optional&amp;);
-
- const xercesc::DOMDocument&amp;
- dom_content_document () const;
-
- xercesc::DOMDocument&amp;
- dom_content_document ();
-
- bool
- null_content () const;
-
- // DOM association.
- //
-public:
- const xercesc::DOMNode*
- _node () const;
-
- xercesc::DOMNode*
- _node ();
-};
- </pre>
-
- <p>When <code>xml_schema::type</code> is used to create an instance
- (as opposed to being a base of a derived type), it represents
- the XML Schema <code>anyType</code> type. <code>anyType</code>
- allows any attributes and any content in any order. In the
- C++/Tree mapping this content can be represented as a DOM
- fragment, similar to XML Schema wildcards (<a href="#2.12">Section
- 2.12, "Mapping for <code>any</code> and
- <code>anyAttribute</code>"</a>).</p>
-
- <p>To enable automatic extraction of <code>anyType</code> content
- during parsing, the <code>--generate-any-type</code> option must be
- specified. Because the DOM API is used to access such content, the
- Xerces-C++ runtime should be initialized by the application prior to
- parsing and should remain initialized for the lifetime of objects
- with the DOM content. For more information on the Xerces-C++ runtime
- initialization see <a href="#3.1">Section 3.1, "Initializing the
- Xerces-C++ Runtime"</a>.</p>
-
- <p>The DOM content is stored as the optional DOM element container
- and the DOM content accessors and modifiers presented above are
- identical to those generated for an optional element wildcard.
- Refer to <a href="#2.12.2">Section 2.12.2, "Mapping for <code>any</code>
- with the Optional Cardinality Class"</a> for details on their
- semantics.</p>
-
- <p>The <code>dom_content_document()</code> function returns the
- DOM document used to store the raw XML content corresponding
- to the <code>anyType</code> instance. It is equivalent to the
- <code>dom_document()</code> function generated for types
- with wildcards.</p>
-
- <p>The <code>null_content()</code> accessor is an optimization function
- that allows us to check for the lack of content without actually
- creating its empty representation, that is, empty DOM document for
- <code>anyType</code> or empty string for <code>anySimpleType</code>
- (see the following section for details on <code>anySimpleType</code>).</p>
-
- <p>For more information on DOM association refer to
- <a href="#5.1">Section 5.1, "DOM Association"</a>.</p>
-
- <h3><a name="2.5.3">2.5.3 Mapping for <code>anySimpleType</code></a></h3>
-
- <p>The XML Schema <code>anySimpleType</code> built-in data type is mapped
- to the <code>xml_schema::simple_type</code> C++ class:</p>
-
- <pre class="c++">
-class simple_type: public type
-{
-public:
- simple_type ();
- simple_type (const C*);
- simple_type (const std::basic_string&lt;C>&amp;);
-
- simple_type (const simple_type&amp;);
-
- simple_type&amp;
- operator= (const simple_type&amp;);
-
- virtual simple_type*
- _clone () const;
-
- // anySimpleType text content.
- //
-public:
- const std::basic_string&lt;C>&amp;
- text_content () const;
-
- std::basic_string&lt;C>&amp;
- text_content ();
-
- void
- text_content (const std::basic_string&lt;C>&amp;);
-};
- </pre>
-
- <p>When <code>xml_schema::simple_type</code> is used to create an instance
- (as opposed to being a base of a derived type), it represents
- the XML Schema <code>anySimpleType</code> type. <code>anySimpleType</code>
- allows any simple content. In the C++/Tree mapping this content can
- be represented as a string and accessed or modified with the
- <code>text_content()</code> functions shown above.</p>
-
- <h3><a name="2.5.4">2.5.4 Mapping for <code>QName</code></a></h3>
-
- <p>The XML Schema <code>QName</code> built-in data type is mapped to the
- <code>xml_schema::qname</code> C++ class:</p>
-
- <pre class="c++">
-class qname: public simple_type
-{
-public:
- qname (const ncname&amp;);
- qname (const uri&amp;, const ncname&amp;);
- qname (const qname&amp;);
-
-public:
- qname&amp;
- operator= (const qname&amp;);
-
-public:
- virtual qname*
- _clone () const;
-
-public:
- bool
- qualified () const;
-
- const uri&amp;
- namespace_ () const;
-
- const ncname&amp;
- name () const;
-};
- </pre>
-
- <p>The <code>qualified</code> accessor function can be used to determine
- if the name is qualified.</p>
-
- <h3><a name="2.5.5">2.5.5 Mapping for <code>IDREF</code></a></h3>
-
- <p>The XML Schema <code>IDREF</code> built-in data type is mapped to the
- <code>xml_schema::idref</code> C++ class. This class implements the
- smart pointer C++ idiom:</p>
-
- <pre class="c++">
-class idref: public ncname
-{
-public:
- idref (const C* s);
- idref (const C* s, std::size_t n);
- idref (std::size_t n, C c);
- idref (const std::basic_string&lt;C>&amp;);
- idref (const std::basic_string&lt;C>&amp;,
- std::size_t pos,
- std::size_t n = npos);
-
-public:
- idref (const idref&amp;);
-
-public:
- virtual idref*
- _clone () const;
-
-public:
- idref&amp;
- operator= (C c);
-
- idref&amp;
- operator= (const C* s);
-
- idref&amp;
- operator= (const std::basic_string&lt;C>&amp;)
-
- idref&amp;
- operator= (const idref&amp;);
-
-public:
- const type*
- operator-> () const;
-
- type*
- operator-> ();
-
- const type&amp;
- operator* () const;
-
- type&amp;
- operator* ();
-
- const type*
- get () const;
-
- type*
- get ();
-
- // Conversion to bool.
- //
-public:
- typedef void (idref::*bool_convertible)();
- operator bool_convertible () const;
-};
- </pre>
-
- <p>The object, <code>idref</code> instance refers to, is the immediate
- container of the matching <code>id</code> instance. For example,
- with the following instance document and schema:
- </p>
-
-
- <pre class="xml">
-&lt;!-- test.xml -->
-&lt;root>
- &lt;object id="obj-1" text="hello"/>
- &lt;reference>obj-1&lt;/reference>
-&lt;/root>
-
-&lt;!-- test.xsd -->
-&lt;schema>
- &lt;complexType name="object_type">
- &lt;attribute name="id" type="ID"/>
- &lt;attribute name="text" type="string"/>
- &lt;/complexType>
-
- &lt;complexType name="root_type">
- &lt;sequence>
- &lt;element name="object" type="object_type"/>
- &lt;element name="reference" type="IDREF"/>
- &lt;/sequence>
- &lt;/complexType>
-
- &lt;element name="root" type="root_type"/>
-&lt;/schema>
- </pre>
-
- <p>The <code>ref</code> instance in the code below will refer to
- an object of type <code>object_type</code>:</p>
-
- <pre class="c++">
-root_type&amp; root = ...;
-xml_schema::idref&amp; ref (root.reference ());
-object_type&amp; obj (dynamic_cast&lt;object_type&amp;> (*ref));
-cout &lt;&lt; obj.text () &lt;&lt; endl;
- </pre>
-
- <p>The smart pointer interface of the <code>idref</code> class always
- returns a pointer or reference to <code>xml_schema::type</code>.
- This means that you will need to manually cast such pointer or
- reference to its real (dynamic) type before you can use it (unless
- all you need is the base interface provided by
- <code>xml_schema::type</code>). As a special extension to the XML
- Schema language, the mapping supports static typing of <code>idref</code>
- references by employing the <code>refType</code> extension attribute.
- The following example illustrates this mechanism:
- </p>
-
- <pre class="xml">
-&lt;!-- test.xsd -->
-&lt;schema
- xmlns:xse="https://www.codesynthesis.com/xmlns/xml-schema-extension">
-
- ...
-
- &lt;element name="reference" type="IDREF" xse:refType="object_type"/>
-
- ...
-
-&lt;/schema>
- </pre>
-
- <p>With this modification we do not need to do manual casting anymore:
- </p>
-
- <pre class="c++">
-root_type&amp; root = ...;
-root_type::reference_type&amp; ref (root.reference ());
-object_type&amp; obj (*ref);
-cout &lt;&lt; ref->text () &lt;&lt; endl;
- </pre>
-
-
- <h3><a name="2.5.6">2.5.6 Mapping for <code>base64Binary</code> and
- <code>hexBinary</code></a></h3>
-
- <p>The XML Schema <code>base64Binary</code> and <code>hexBinary</code>
- built-in data types are mapped to the
- <code>xml_schema::base64_binary</code> and
- <code>xml_schema::hex_binary</code> C++ classes, respectively. The
- <code>base64_binary</code> and <code>hex_binary</code> classes
- support a simple buffer abstraction by inheriting from the
- <code>xml_schema::buffer</code> class:
- </p>
-
- <pre class="c++">
-class bounds: public virtual exception
-{
-public:
- virtual const char*
- what () const throw ();
-};
-
-class buffer
-{
-public:
- typedef std::size_t size_t;
-
-public:
- buffer (size_t size = 0);
- buffer (size_t size, size_t capacity);
- buffer (const void* data, size_t size);
- buffer (const void* data, size_t size, size_t capacity);
- buffer (void* data,
- size_t size,
- size_t capacity,
- bool assume_ownership);
-
-public:
- buffer (const buffer&amp;);
-
- buffer&amp;
- operator= (const buffer&amp;);
-
- void
- swap (buffer&amp;);
-
-public:
- size_t
- capacity () const;
-
- bool
- capacity (size_t);
-
-public:
- size_t
- size () const;
-
- bool
- size (size_t);
-
-public:
- const char*
- data () const;
-
- char*
- data ();
-
- const char*
- begin () const;
-
- char*
- begin ();
-
- const char*
- end () const;
-
- char*
- end ();
-};
- </pre>
-
- <p>The last overloaded constructor reuses an existing data buffer instead
- of making a copy. If the <code>assume_ownership</code> argument is
- <code>true</code>, the instance assumes ownership of the
- memory block pointed to by the <code>data</code> argument and will
- eventually release it by calling <code>operator delete</code>. The
- <code>capacity</code> and <code>size</code> modifier functions return
- <code>true</code> if the underlying buffer has moved.
- </p>
-
- <p>The <code>bounds</code> exception is thrown if the constructor
- arguments violate the <code>(size&nbsp;&lt;=&nbsp;capacity)</code>
- constraint.</p>
-
- <p>The <code>base64_binary</code> and <code>hex_binary</code> classes
- support the <code>buffer</code> interface and perform automatic
- decoding/encoding from/to the Base64 and Hex formats, respectively:
- </p>
-
- <pre class="c++">
-class base64_binary: public simple_type, public buffer
-{
-public:
- base64_binary (size_t size = 0);
- base64_binary (size_t size, size_t capacity);
- base64_binary (const void* data, size_t size);
- base64_binary (const void* data, size_t size, size_t capacity);
- base64_binary (void* data,
- size_t size,
- size_t capacity,
- bool assume_ownership);
-
-public:
- base64_binary (const base64_binary&amp;);
-
- base64_binary&amp;
- operator= (const base64_binary&amp;);
-
- virtual base64_binary*
- _clone () const;
-
-public:
- std::basic_string&lt;C>
- encode () const;
-};
- </pre>
-
- <pre class="c++">
-class hex_binary: public simple_type, public buffer
-{
-public:
- hex_binary (size_t size = 0);
- hex_binary (size_t size, size_t capacity);
- hex_binary (const void* data, size_t size);
- hex_binary (const void* data, size_t size, size_t capacity);
- hex_binary (void* data,
- size_t size,
- size_t capacity,
- bool assume_ownership);
-
-public:
- hex_binary (const hex_binary&amp;);
-
- hex_binary&amp;
- operator= (const hex_binary&amp;);
-
- virtual hex_binary*
- _clone () const;
-
-public:
- std::basic_string&lt;C>
- encode () const;
-};
- </pre>
-
-
- <h2><a name="2.5.7">2.5.7 Time Zone Representation</a></h2>
-
- <p>The <code>date</code>, <code>dateTime</code>, <code>gDay</code>,
- <code>gMonth</code>, <code>gMonthDay</code>, <code>gYear</code>,
- <code>gYearMonth</code>, and <code>time</code> XML Schema built-in
- types all include an optional time zone component. The following
- <code>xml_schema::time_zone</code> base class is used to represent
- this information:</p>
-
- <pre class="c++">
-class time_zone
-{
-public:
- time_zone ();
- time_zone (short hours, short minutes);
-
- bool
- zone_present () const;
-
- void
- zone_reset ();
-
- short
- zone_hours () const;
-
- void
- zone_hours (short);
-
- short
- zone_minutes () const;
-
- void
- zone_minutes (short);
-};
-
-bool
-operator== (const time_zone&amp;, const time_zone&amp;);
-
-bool
-operator!= (const time_zone&amp;, const time_zone&amp;);
- </pre>
-
- <p>The <code>zone_present()</code> accessor function returns <code>true</code>
- if the time zone is specified. The <code>zone_reset()</code> modifier
- function resets the time zone object to the <em>not specified</em>
- state. If the time zone offset is negative then both hours and
- minutes components are represented as negative integers.</p>
-
-
- <h2><a name="2.5.8">2.5.8 Mapping for <code>date</code></a></h2>
-
- <p>The XML Schema <code>date</code> built-in data type is mapped to the
- <code>xml_schema::date</code> C++ class which represents a year, a day,
- and a month with an optional time zone. Its interface is presented
- below. For more information on the base <code>xml_schema::time_zone</code>
- class refer to <a href="#2.5.7">Section 2.5.7, "Time Zone
- Representation"</a>.</p>
-
- <pre class="c++">
-class date: public simple_type, public time_zone
-{
-public:
- date (int year, unsigned short month, unsigned short day);
- date (int year, unsigned short month, unsigned short day,
- short zone_hours, short zone_minutes);
-
-public:
- date (const date&amp;);
-
- date&amp;
- operator= (const date&amp;);
-
- virtual date*
- _clone () const;
-
-public:
- int
- year () const;
-
- void
- year (int);
-
- unsigned short
- month () const;
-
- void
- month (unsigned short);
-
- unsigned short
- day () const;
-
- void
- day (unsigned short);
-};
-
-bool
-operator== (const date&amp;, const date&amp;);
-
-bool
-operator!= (const date&amp;, const date&amp;);
- </pre>
-
- <h2><a name="2.5.9">2.5.9 Mapping for <code>dateTime</code></a></h2>
-
- <p>The XML Schema <code>dateTime</code> built-in data type is mapped to the
- <code>xml_schema::date_time</code> C++ class which represents a year, a month,
- a day, hours, minutes, and seconds with an optional time zone. Its interface
- is presented below. For more information on the base
- <code>xml_schema::time_zone</code> class refer to <a href="#2.5.7">Section
- 2.5.7, "Time Zone Representation"</a>.</p>
-
- <pre class="c++">
-class date_time: public simple_type, public time_zone
-{
-public:
- date_time (int year, unsigned short month, unsigned short day,
- unsigned short hours, unsigned short minutes,
- double seconds);
-
- date_time (int year, unsigned short month, unsigned short day,
- unsigned short hours, unsigned short minutes,
- double seconds, short zone_hours, short zone_minutes);
-public:
- date_time (const date_time&amp;);
-
- date_time&amp;
- operator= (const date_time&amp;);
-
- virtual date_time*
- _clone () const;
-
-public:
- int
- year () const;
-
- void
- year (int);
-
- unsigned short
- month () const;
-
- void
- month (unsigned short);
-
- unsigned short
- day () const;
-
- void
- day (unsigned short);
-
- unsigned short
- hours () const;
-
- void
- hours (unsigned short);
-
- unsigned short
- minutes () const;
-
- void
- minutes (unsigned short);
-
- double
- seconds () const;
-
- void
- seconds (double);
-};
-
-bool
-operator== (const date_time&amp;, const date_time&amp;);
-
-bool
-operator!= (const date_time&amp;, const date_time&amp;);
- </pre>
-
-
- <h2><a name="2.5.10">2.5.10 Mapping for <code>duration</code></a></h2>
-
- <p>The XML Schema <code>duration</code> built-in data type is mapped to the
- <code>xml_schema::duration</code> C++ class which represents a potentially
- negative duration in the form of years, months, days, hours, minutes,
- and seconds. Its interface is presented below.</p>
-
- <pre class="c++">
-class duration: public simple_type
-{
-public:
- duration (bool negative,
- unsigned int years, unsigned int months, unsigned int days,
- unsigned int hours, unsigned int minutes, double seconds);
-public:
- duration (const duration&amp;);
-
- duration&amp;
- operator= (const duration&amp;);
-
- virtual duration*
- _clone () const;
-
-public:
- bool
- negative () const;
-
- void
- negative (bool);
-
- unsigned int
- years () const;
-
- void
- years (unsigned int);
-
- unsigned int
- months () const;
-
- void
- months (unsigned int);
-
- unsigned int
- days () const;
-
- void
- days (unsigned int);
-
- unsigned int
- hours () const;
-
- void
- hours (unsigned int);
-
- unsigned int
- minutes () const;
-
- void
- minutes (unsigned int);
-
- double
- seconds () const;
-
- void
- seconds (double);
-};
-
-bool
-operator== (const duration&amp;, const duration&amp;);
-
-bool
-operator!= (const duration&amp;, const duration&amp;);
- </pre>
-
-
- <h2><a name="2.5.11">2.5.11 Mapping for <code>gDay</code></a></h2>
-
- <p>The XML Schema <code>gDay</code> built-in data type is mapped to the
- <code>xml_schema::gday</code> C++ class which represents a day of the
- month with an optional time zone. Its interface is presented below.
- For more information on the base <code>xml_schema::time_zone</code>
- class refer to <a href="#2.5.7">Section 2.5.7, "Time Zone
- Representation"</a>.</p>
-
- <pre class="c++">
-class gday: public simple_type, public time_zone
-{
-public:
- explicit
- gday (unsigned short day);
- gday (unsigned short day, short zone_hours, short zone_minutes);
-
-public:
- gday (const gday&amp;);
-
- gday&amp;
- operator= (const gday&amp;);
-
- virtual gday*
- _clone () const;
-
-public:
- unsigned short
- day () const;
-
- void
- day (unsigned short);
-};
-
-bool
-operator== (const gday&amp;, const gday&amp;);
-
-bool
-operator!= (const gday&amp;, const gday&amp;);
- </pre>
-
-
- <h2><a name="2.5.12">2.5.12 Mapping for <code>gMonth</code></a></h2>
-
- <p>The XML Schema <code>gMonth</code> built-in data type is mapped to the
- <code>xml_schema::gmonth</code> C++ class which represents a month of the
- year with an optional time zone. Its interface is presented below.
- For more information on the base <code>xml_schema::time_zone</code>
- class refer to <a href="#2.5.7">Section 2.5.7, "Time Zone
- Representation"</a>.</p>
-
- <pre class="c++">
-class gmonth: public simple_type, public time_zone
-{
-public:
- explicit
- gmonth (unsigned short month);
- gmonth (unsigned short month,
- short zone_hours, short zone_minutes);
-
-public:
- gmonth (const gmonth&amp;);
-
- gmonth&amp;
- operator= (const gmonth&amp;);
-
- virtual gmonth*
- _clone () const;
-
-public:
- unsigned short
- month () const;
-
- void
- month (unsigned short);
-};
-
-bool
-operator== (const gmonth&amp;, const gmonth&amp;);
-
-bool
-operator!= (const gmonth&amp;, const gmonth&amp;);
- </pre>
-
-
- <h2><a name="2.5.13">2.5.13 Mapping for <code>gMonthDay</code></a></h2>
-
- <p>The XML Schema <code>gMonthDay</code> built-in data type is mapped to the
- <code>xml_schema::gmonth_day</code> C++ class which represents a day and
- a month of the year with an optional time zone. Its interface is presented
- below. For more information on the base <code>xml_schema::time_zone</code>
- class refer to <a href="#2.5.7">Section 2.5.7, "Time Zone
- Representation"</a>.</p>
-
- <pre class="c++">
-class gmonth_day: public simple_type, public time_zone
-{
-public:
- gmonth_day (unsigned short month, unsigned short day);
- gmonth_day (unsigned short month, unsigned short day,
- short zone_hours, short zone_minutes);
-
-public:
- gmonth_day (const gmonth_day&amp;);
-
- gmonth_day&amp;
- operator= (const gmonth_day&amp;);
-
- virtual gmonth_day*
- _clone () const;
-
-public:
- unsigned short
- month () const;
-
- void
- month (unsigned short);
-
- unsigned short
- day () const;
-
- void
- day (unsigned short);
-};
-
-bool
-operator== (const gmonth_day&amp;, const gmonth_day&amp;);
-
-bool
-operator!= (const gmonth_day&amp;, const gmonth_day&amp;);
- </pre>
-
-
- <h2><a name="2.5.14">2.5.14 Mapping for <code>gYear</code></a></h2>
-
- <p>The XML Schema <code>gYear</code> built-in data type is mapped to the
- <code>xml_schema::gyear</code> C++ class which represents a year with
- an optional time zone. Its interface is presented below. For more
- information on the base <code>xml_schema::time_zone</code> class refer
- to <a href="#2.5.7">Section 2.5.7, "Time Zone Representation"</a>.</p>
-
- <pre class="c++">
-class gyear: public simple_type, public time_zone
-{
-public:
- explicit
- gyear (int year);
- gyear (int year, short zone_hours, short zone_minutes);
-
-public:
- gyear (const gyear&amp;);
-
- gyear&amp;
- operator= (const gyear&amp;);
-
- virtual gyear*
- _clone () const;
-
-public:
- int
- year () const;
-
- void
- year (int);
-};
-
-bool
-operator== (const gyear&amp;, const gyear&amp;);
-
-bool
-operator!= (const gyear&amp;, const gyear&amp;);
- </pre>
-
-
- <h2><a name="2.5.15">2.5.15 Mapping for <code>gYearMonth</code></a></h2>
-
- <p>The XML Schema <code>gYearMonth</code> built-in data type is mapped to
- the <code>xml_schema::gyear_month</code> C++ class which represents
- a year and a month with an optional time zone. Its interface is presented
- below. For more information on the base <code>xml_schema::time_zone</code>
- class refer to <a href="#2.5.7">Section 2.5.7, "Time Zone
- Representation"</a>.</p>
-
- <pre class="c++">
-class gyear_month: public simple_type, public time_zone
-{
-public:
- gyear_month (int year, unsigned short month);
- gyear_month (int year, unsigned short month,
- short zone_hours, short zone_minutes);
-public:
- gyear_month (const gyear_month&amp;);
-
- gyear_month&amp;
- operator= (const gyear_month&amp;);
-
- virtual gyear_month*
- _clone () const;
-
-public:
- int
- year () const;
-
- void
- year (int);
-
- unsigned short
- month () const;
-
- void
- month (unsigned short);
-};
-
-bool
-operator== (const gyear_month&amp;, const gyear_month&amp;);
-
-bool
-operator!= (const gyear_month&amp;, const gyear_month&amp;);
- </pre>
-
-
- <h2><a name="2.5.16">2.5.16 Mapping for <code>time</code></a></h2>
-
- <p>The XML Schema <code>time</code> built-in data type is mapped to
- the <code>xml_schema::time</code> C++ class which represents hours,
- minutes, and seconds with an optional time zone. Its interface is
- presented below. For more information on the base
- <code>xml_schema::time_zone</code> class refer to
- <a href="#2.5.7">Section 2.5.7, "Time Zone Representation"</a>.</p>
-
- <pre class="c++">
-class time: public simple_type, public time_zone
-{
-public:
- time (unsigned short hours, unsigned short minutes, double seconds);
- time (unsigned short hours, unsigned short minutes, double seconds,
- short zone_hours, short zone_minutes);
-
-public:
- time (const time&amp;);
-
- time&amp;
- operator= (const time&amp;);
-
- virtual time*
- _clone () const;
-
-public:
- unsigned short
- hours () const;
-
- void
- hours (unsigned short);
-
- unsigned short
- minutes () const;
-
- void
- minutes (unsigned short);
-
- double
- seconds () const;
-
- void
- seconds (double);
-};
-
-bool
-operator== (const time&amp;, const time&amp;);
-
-bool
-operator!= (const time&amp;, const time&amp;);
- </pre>
-
-
- <!-- Mapping for Simple Types -->
-
- <h2><a name="2.6">2.6 Mapping for Simple Types</a></h2>
-
- <p>An XML Schema simple type is mapped to a C++ class with the same
- name as the simple type. The class defines a public copy constructor,
- a public copy assignment operator, and a public virtual
- <code>_clone</code> function. The <code>_clone</code> function is
- declared <code>const</code>, does not take any arguments, and returns
- a pointer to a complete copy of the instance allocated in the free
- store. The <code>_clone</code> function shall be used to make copies
- when static type and dynamic type of the instance may differ (see
- <a href="#2.11">Section 2.11, "Mapping for <code>xsi:type</code>
- and Substitution Groups"</a>). For instance:</p>
-
- <pre class="xml">
-&lt;simpleType name="object">
- ...
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: ...
-{
-public:
- object (const object&amp;);
-
-public:
- object&amp;
- operator= (const object&amp;);
-
-public:
- virtual object*
- _clone () const;
-
- ...
-
-};
- </pre>
-
- <p>The base class specification and the rest of the class definition
- depend on the type of derivation used to define the simple type. </p>
-
-
- <h3><a name="2.6.1">2.6.1 Mapping for Derivation by Restriction</a></h3>
-
- <p>XML Schema derivation by restriction is mapped to C++ public
- inheritance. The base type of the restriction becomes the base
- type for the resulting C++ class. In addition to the members described
- in <a href="#2.6">Section 2.6, "Mapping for Simple Types"</a>, the
- resulting C++ class defines a public constructor with the base type
- as its single argument. For instance:</p>
-
- <pre class="xml">
-&lt;simpleType name="object">
- &lt;restriction base="base">
- ...
- &lt;/restriction>
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public base
-{
-public:
- object (const base&amp;);
- object (const object&amp;);
-
-public:
- object&amp;
- operator= (const object&amp;);
-
-public:
- virtual object*
- _clone () const;
-};
- </pre>
-
-
- <h3><a name="2.6.2">2.6.2 Mapping for Enumerations</a></h3>
-
-<p>XML Schema restriction by enumeration is mapped to a C++ class
- with semantics similar to C++ <code>enum</code>. Each XML Schema
- enumeration element is mapped to a C++ enumerator with the
- name derived from the <code>value</code> attribute and defined
- in the class scope. In addition to the members
- described in <a href="#2.6">Section 2.6, "Mapping for Simple Types"</a>,
- the resulting C++ class defines a public constructor that can be called
- with one of the enumerators as its single argument, a public constructor
- that can be called with enumeration's base value as its single
- argument, a public assignment operator that can be used to assign the
- value of one of the enumerators, and a public implicit conversion
- operator to the underlying C++ enum type.</p>
-
-<p>Furthermore, for string-based enumeration types, the resulting C++
- class defines a public constructor with a single argument of type
- <code>const C*</code> and a public constructor with a single
- argument of type <code>const std::basic_string&lt;C>&amp;</code>.
- For instance:</p>
-
- <pre class="xml">
-&lt;simpleType name="color">
- &lt;restriction base="string">
- &lt;enumeration value="red"/>
- &lt;enumeration value="green"/>
- &lt;enumeration value="blue"/>
- &lt;/restriction>
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class color: public xml_schema::string
-{
-public:
- enum value
- {
- red,
- green,
- blue
- };
-
-public:
- color (value);
- color (const C*);
- color (const std::basic_string&lt;C>&amp;);
- color (const xml_schema::string&amp;);
- color (const color&amp;);
-
-public:
- color&amp;
- operator= (value);
-
- color&amp;
- operator= (const color&amp;);
-
-public:
- virtual color*
- _clone () const;
-
-public:
- operator value () const;
-};
- </pre>
-
- <h3><a name="2.6.3">2.6.3 Mapping for Derivation by List</a></h3>
-
- <p>XML Schema derivation by list is mapped to C++ public
- inheritance from <code>xml_schema::simple_type</code>
- (<a href="#2.5.3">Section 2.5.3, "Mapping for
- <code>anySimpleType</code>"</a>) and a suitable sequence type.
- The list item type becomes the element type of the sequence.
- In addition to the members described in <a href="#2.6">Section 2.6,
- "Mapping for Simple Types"</a>, the resulting C++ class defines
- a public default constructor, a public constructor
- with the first argument of type <code>size_type</code> and
- the second argument of list item type that creates
- a list object with the specified number of copies of the specified
- element value, and a public constructor with the two arguments
- of an input iterator type that creates a list object from an
- iterator range. For instance:
- </p>
-
- <pre class="xml">
-&lt;simpleType name="int_list">
- &lt;list itemType="int"/>
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class int_list: public simple_type,
- public sequence&lt;int>
-{
-public:
- int_list ();
- int_list (size_type n, int x);
-
- template &lt;typename I>
- int_list (const I&amp; begin, const I&amp; end);
- int_list (const int_list&amp;);
-
-public:
- int_list&amp;
- operator= (const int_list&amp;);
-
-public:
- virtual int_list*
- _clone () const;
-};
- </pre>
-
- <p>The <code>sequence</code> class template is defined in an
- implementation-specific namespace. It conforms to the
- 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
- 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 (<code>std::auto_ptr</code>
- or <code>std::unique_ptr</code>, depending on the C++ standard
- selected) to the element type. These functions assume ownership
- of the pointed to object and reset the passed automatic pointer.
- </p>
-
- <h3><a name="2.6.4">2.6.4 Mapping for Derivation by Union</a></h3>
-
- <p>XML Schema derivation by union is mapped to C++ public
- inheritance from <code>xml_schema::simple_type</code>
- (<a href="#2.5.3">Section 2.5.3, "Mapping for
- <code>anySimpleType</code>"</a>) and <code>std::basic_string&lt;C></code>.
- In addition to the members described in <a href="#2.6">Section 2.6,
- "Mapping for Simple Types"</a>, the resulting C++ class defines a
- public constructor with a single argument of type <code>const C*</code>
- and a public constructor with a single argument of type
- <code>const std::basic_string&lt;C>&amp;</code>. For instance:
- </p>
-
- <pre class="xml">
-&lt;simpleType name="int_string_union">
- &lt;xsd:union memberTypes="xsd:int xsd:string"/>
-&lt;/simpleType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class int_string_union: public simple_type,
- public std::basic_string&lt;C>
-{
-public:
- int_string_union (const C*);
- int_string_union (const std::basic_string&lt;C>&amp;);
- int_string_union (const int_string_union&amp;);
-
-public:
- int_string_union&amp;
- operator= (const int_string_union&amp;);
-
-public:
- virtual int_string_union*
- _clone () const;
-};
- </pre>
-
- <h2><a name="2.7">2.7 Mapping for Complex Types</a></h2>
-
- <p>An XML Schema complex type is mapped to a C++ class with the same
- name as the complex type. The class defines a public copy constructor,
- a public copy assignment operator, and a public virtual
- <code>_clone</code> function. The <code>_clone</code> function is
- declared <code>const</code>, does not take any arguments, and returns
- a pointer to a complete copy of the instance allocated in the free
- store. The <code>_clone</code> function shall be used to make copies
- when static type and dynamic type of the instance may differ (see
- <a href="#2.11">Section 2.11, "Mapping for <code>xsi:type</code>
- and Substitution Groups"</a>).</p>
-
- <p>Additionally, the resulting C++ class
- defines two public constructors that take an initializer for each
- member of the complex type and all its base types that belongs to
- the One cardinality class (see <a href="#2.8">Section 2.8, "Mapping
- for Local Elements and Attributes"</a>). In the first constructor,
- the arguments are passed as constant references and the newly created
- instance is initialized with copies of the passed objects. In the
- second constructor, arguments that are complex types (that is,
- they themselves contain elements or attributes) are passed as
- either <code>std::auto_ptr</code> (C++98) or <code>std::unique_ptr</code>
- (C++11), depending on the C++ standard selected. In this case the newly
- created instance is directly initialized with and assumes ownership
- of the pointed to objects and the <code>std::[auto|unique]_ptr</code>
- arguments are reset to <code>0</code>. For instance:</p>
-
- <pre class="xml">
-&lt;complexType name="complex">
- &lt;sequence>
- &lt;element name="a" type="int"/>
- &lt;element name="b" type="string"/>
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="s-one" type="boolean"/>
- &lt;element name="c-one" type="complex"/>
- &lt;element name="optional" type="int" minOccurs="0"/>
- &lt;element name="sequence" type="string" maxOccurs="unbounded"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class complex: public xml_schema::type
-{
-public:
- object (const int&amp; a, const xml_schema::string&amp; b);
- object (const complex&amp;);
-
-public:
- object&amp;
- operator= (const complex&amp;);
-
-public:
- virtual complex*
- _clone () const;
-
- ...
-
-};
-
-class object: public xml_schema::type
-{
-public:
- object (const bool&amp; s_one, const complex&amp; c_one);
- object (const bool&amp; s_one, std::[auto|unique]_ptr&lt;complex> c_one);
- object (const object&amp;);
-
-public:
- object&amp;
- operator= (const object&amp;);
-
-public:
- virtual object*
- _clone () const;
-
- ...
-
-};
- </pre>
-
- <p>Notice that the generated <code>complex</code> class does not
- have the second (<code>std::[auto|unique]_ptr</code>) version of the
- constructor since all its required members are of simple types.</p>
-
- <p>If an XML Schema complex type has an ultimate base which is an XML
- Schema simple type then the resulting C++ class also defines a public
- constructor that takes an initializer for the base type as well as
- for each member of the complex type and all its base types that
- belongs to the One cardinality class. For instance:</p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;simpleContent>
- &lt;extension base="date">
- &lt;attribute name="lang" type="language" use="required"/>
- &lt;/extension>
- &lt;/simpleContent>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::string
-{
-public:
- object (const xml_schema::language&amp; lang);
-
- object (const xml_schema::date&amp; base,
- const xml_schema::language&amp; lang);
-
- ...
-
-};
- </pre>
-
- <p>Furthermore, for string-based XML Schema complex types, the resulting C++
- class also defines two public constructors with the first arguments
- of type <code>const C*</code> and <code>std::basic_string&lt;C>&amp;</code>,
- respectively, followed by arguments for each member of the complex
- type and all its base types that belongs to the One cardinality
- class. For enumeration-based complex types the resulting C++
- class also defines a public constructor with the first arguments
- of the underlying enum type followed by arguments for each member
- of the complex type and all its base types that belongs to the One
- cardinality class. For instance:</p>
-
- <pre class="xml">
-&lt;simpleType name="color">
- &lt;restriction base="string">
- &lt;enumeration value="red"/>
- &lt;enumeration value="green"/>
- &lt;enumeration value="blue"/>
- &lt;/restriction>
-&lt;/simpleType>
-
-&lt;complexType name="object">
- &lt;simpleContent>
- &lt;extension base="color">
- &lt;attribute name="lang" type="language" use="required"/>
- &lt;/extension>
- &lt;/simpleContent>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class color: public xml_schema::string
-{
-public:
- enum value
- {
- red,
- green,
- blue
- };
-
-public:
- color (value);
- color (const C*);
- color (const std::basic_string&lt;C>&amp;);
-
- ...
-
-};
-
-class object: color
-{
-public:
- object (const color&amp; base,
- const xml_schema::language&amp; lang);
-
- object (const color::value&amp; base,
- const xml_schema::language&amp; lang);
-
- object (const C* base,
- const xml_schema::language&amp; lang);
-
- object (const std::basic_string&lt;C>&amp; base,
- const xml_schema::language&amp; lang);
-
- ...
-
-};
- </pre>
-
- <p>Additional constructors can be requested with the
- <code>--generate-default-ctor</code> and
- <code>--generate-from-base-ctor</code> options. See the
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a> for details.</p>
-
- <p>If an XML Schema complex type is not explicitly derived from any type,
- the resulting C++ class is derived from <code>xml_schema::type</code>.
- In cases where an XML Schema complex type is defined using derivation
- by extension or restriction, the resulting C++ base class specification
- depends on the type of derivation and is described in the subsequent
- sections.
- </p>
-
- <p>The mapping for elements and attributes that are defined in a complex
- type is described in <a href="#2.8">Section 2.8, "Mapping for Local
- Elements and Attributes"</a>.
- </p>
-
- <h3><a name="2.7.1">2.7.1 Mapping for Derivation by Extension</a></h3>
-
- <p>XML Schema derivation by extension is mapped to C++ public
- inheritance. The base type of the extension becomes the base
- type for the resulting C++ class.
- </p>
-
- <h3><a name="2.7.2">2.7.2 Mapping for Derivation by Restriction</a></h3>
-
- <p>XML Schema derivation by restriction is mapped to C++ public
- inheritance. The base type of the restriction becomes the base
- type for the resulting C++ class. XML Schema elements and
- attributes defined within restriction do not result in any
- definitions in the resulting C++ class. Instead, corresponding
- (unrestricted) definitions are inherited from the base class.
- In the future versions of this mapping, such elements and
- attributes may result in redefinitions of accessors and
- modifiers to reflect their restricted semantics.
- </p>
-
- <!-- 2.8 Mapping for Local Elements and Attributes -->
-
- <h2><a name="2.8">2.8 Mapping for Local Elements and Attributes</a></h2>
-
- <p>XML Schema element and attribute definitions are called local
- if they appear within a complex type definition, an element group
- definition, or an attribute group definitions.
- </p>
-
- <p>Local XML Schema element and attribute definitions have the same
- C++ mapping. Therefore, in this section, local elements and
- attributes are collectively called members.
- </p>
-
- <p>While there are many different member cardinality combinations
- (determined by the <code>use</code> attribute for attributes and
- the <code>minOccurs</code> and <code>maxOccurs</code> attributes
- for elements), the mapping divides all possible cardinality
- combinations into three cardinality classes:
- </p>
-
- <dl>
- <dt><i>one</i></dt>
- <dd>attributes: <code>use == "required"</code></dd>
- <dd>attributes: <code>use == "optional"</code> and has default or fixed value</dd>
- <dd>elements: <code>minOccurs == "1"</code> and <code>maxOccurs == "1"</code></dd>
-
- <dt><i>optional</i></dt>
- <dd>attributes: <code>use == "optional"</code> and doesn't have default or fixed value</dd>
- <dd>elements: <code>minOccurs == "0"</code> and <code>maxOccurs == "1"</code></dd>
-
- <dt><i>sequence</i></dt>
- <dd>elements: <code>maxOccurs > "1"</code></dd>
- </dl>
-
- <p>An optional attribute with a default or fixed value acquires this value
- if the attribute hasn't been specified in an instance document (see
- <a href="#A">Appendix A, "Default and Fixed Values"</a>). This
- mapping places such optional attributes to the One cardinality
- class.</p>
-
- <p>A member is mapped to a set of public type definitions
- (<code>typedef</code>s) and a set of public accessor and modifier
- functions. Type definitions have names derived from the member's
- name. The accessor and modifier functions have the same name as the
- member. For example:
- </p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="member" type="string"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- typedef xml_schema::string member_type;
-
- const member_type&amp;
- member () const;
-
- ...
-
-};
- </pre>
-
- <p>In addition, if a member has a default or fixed value, a static
- accessor function is generated that returns this value. For
- example:</p>
-
-<pre class="xml">
-&lt;complexType name="object">
- &lt;attribute name="data" type="string" default="test"/>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- typedef xml_schema::string data_type;
-
- const data_type&amp;
- data () const;
-
- static const data_type&amp;
- data_default_value ();
-
- ...
-
-};
- </pre>
-
- <p>Names and semantics of type definitions for the member as well
- as signatures of the accessor and modifier functions depend on
- the member's cardinality class and are described in the following
- sub-sections.
- </p>
-
-
- <h3><a name="2.8.1">2.8.1 Mapping for Members with the One Cardinality Class</a></h3>
-
- <p>For the One cardinality class, the type definitions consist of
- an alias for the member's type with the name created by appending
- the <code>_type</code> suffix to the member's name.
- </p>
-
- <p>The accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to the
- member and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the member and can
- be used for read-write access.
- </p>
-
- <p>The first modifier function expects an argument of type reference to
- constant of the member's type. It makes a deep copy of its argument.
- Except for member's types that are mapped to fundamental C++ types,
- the second modifier function is provided that expects an argument
- of type automatic pointer (<code>std::auto_ptr</code> or
- <code>std::unique_ptr</code>, depending on the C++ standard selected)
- to the member's type. It assumes ownership of the pointed to object
- and resets the passed automatic pointer. For instance:</p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="member" type="string"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef xml_schema::string member_type;
-
- // Accessors.
- //
- const member_type&amp;
- member () const;
-
- member_type&amp;
- member ();
-
- // Modifiers.
- //
- void
- member (const member_type&amp;);
-
- void
- member (std::[auto|unique]_ptr&lt;member_type>);
- ...
-
-};
- </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: public xml_schema::type
-{
-public:
- ...
-
- std::[auto|unique]_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>
-
- <pre class="c++">
-void
-f (object&amp; o)
-{
- using xml_schema::string;
-
- 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
-
- // C++98 version.
- //
- std::auto_ptr&lt;string> p (new string ("hello"));
- o.member (p); // set, assumes ownership
- p = o.detach_member (); // detach, member is uninitialized
- o.member (p); // re-attach
-
- // C++11 version.
- //
- std::unique_ptr&lt;string> p (new string ("hello"));
- o.member (std::move (p)); // set, assumes ownership
- p = o.detach_member (); // detach, member is uninitialized
- o.member (std::move (p)); // re-attach
-}
- </pre>
-
-
-<h3><a name="2.8.2">2.8.2 Mapping for Members with the Optional Cardinality Class</a></h3>
-
- <p>For the Optional cardinality class, the type definitions consist of
- an alias for the member's type with the name created by appending
- the <code>_type</code> suffix to the member's name and an alias for
- the container type with the name created by appending the
- <code>_optional</code> suffix to the member's name.
- </p>
-
- <p>Unlike accessor functions for the One cardinality class, accessor
- functions for the Optional cardinality class return references to
- corresponding containers rather than directly to members. The
- accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to
- the container and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the container
- and can be used for read-write access.
- </p>
-
- <p>The modifier functions are overloaded for the member's
- type and the container type. The first modifier function
- expects an argument of type reference to constant of the
- member's type. It makes a deep copy of its argument.
- Except for member's types that are mapped to fundamental C++ types,
- the second modifier function is provided that expects an argument
- of type automatic pointer (<code>std::auto_ptr</code> or
- <code>std::unique_ptr</code>, depending on the C++ standard selected)
- to the member's type. It assumes ownership of the pointed to object
- and resets the passed automatic pointer. The last modifier function
- expects an argument of type reference to constant of the container
- type. It makes a deep copy of its argument. For instance:
- </p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="member" type="string" minOccurs="0"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef xml_schema::string member_type;
- typedef optional&lt;member_type> member_optional;
-
- // Accessors.
- //
- const member_optional&amp;
- member () const;
-
- member_optional&amp;
- member ();
-
- // Modifiers.
- //
- void
- member (const member_type&amp;);
-
- void
- member (std::[auto|unique]_ptr&lt;member_type>);
-
- void
- member (const member_optional&amp;);
-
- ...
-
-};
- </pre>
-
-
- <p>The <code>optional</code> class template is defined in an
- implementation-specific namespace and has the following
- interface. The <code>[auto|unique]_ptr</code>-based constructor
- and modifier function are only available if the template
- argument is not a fundamental C++ type.
- </p>
-
- <pre class="c++">
-template &lt;typename X>
-class optional
-{
-public:
- optional ();
-
- // Makes a deep copy.
- //
- explicit
- optional (const X&amp;);
-
- // Assumes ownership.
- //
- explicit
- optional (std::[auto|unique]_ptr&lt;X>);
-
- optional (const optional&amp;);
-
-public:
- optional&amp;
- operator= (const X&amp;);
-
- optional&amp;
- operator= (const optional&amp;);
-
- // Pointer-like interface.
- //
-public:
- const X*
- operator-> () const;
-
- X*
- operator-> ();
-
- const X&amp;
- operator* () const;
-
- X&amp;
- operator* ();
-
- typedef void (optional::*bool_convertible) ();
- operator bool_convertible () const;
-
- // Get/set interface.
- //
-public:
- bool
- present () const;
-
- const X&amp;
- get () const;
-
- X&amp;
- get ();
-
- // Makes a deep copy.
- //
- void
- set (const X&amp;);
-
- // Assumes ownership.
- //
- void
- set (std::[auto|unique]_ptr&lt;X>);
-
- // Detach and return the contained value.
- //
- std::[auto|unique]_ptr&lt;X>
- detach ();
-
- void
- reset ();
-};
-
-template &lt;typename X>
-bool
-operator== (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
-
-template &lt;typename X>
-bool
-operator!= (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
-
-template &lt;typename X>
-bool
-operator&lt; (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
-
-template &lt;typename X>
-bool
-operator> (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
-
-template &lt;typename X>
-bool
-operator&lt;= (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
-
-template &lt;typename X>
-bool
-operator>= (const optional&lt;X>&amp;, const optional&lt;X>&amp;);
- </pre>
-
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o)
-{
- using xml_schema::string;
-
- if (o.member ().present ()) // test
- {
- string&amp; s (o.member ().get ()); // get
- o.member ("hello"); // set, deep copy
- o.member ().set ("hello"); // set, deep copy
- o.member ().reset (); // reset
- }
-
- // Same as above but using pointer notation:
- //
- if (o.member ()) // test
- {
- string&amp; s (*o.member ()); // get
- o.member ("hello"); // set, deep copy
- *o.member () = "hello"; // set, deep copy
- o.member ().reset (); // reset
- }
-
- // C++98 version.
- //
- std::auto_ptr&lt;string> p (new string ("hello"));
- o.member (p); // set, assumes ownership
-
- 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
-
- // C++11 version.
- //
- std::unique_ptr&lt;string> p (new string ("hello"));
- o.member (std::move (p)); // set, assumes ownership
-
- p.reset (new string ("hello"));
- o.member ().set (std::move (p)); // set, assumes ownership
-
- p = o.member ().detach (); // detach, member is reset
- o.member ().set (std::move (p)); // re-attach
-}
- </pre>
-
-
- <h3><a name="2.8.3">2.8.3 Mapping for Members with the Sequence Cardinality Class</a></h3>
-
- <p>For the Sequence cardinality class, the type definitions consist of an
- alias for the member's type with the name created by appending
- the <code>_type</code> suffix to the member's name, an alias of
- the container type with the name created by appending the
- <code>_sequence</code> suffix to the member's name, an alias of
- the iterator type with the name created by appending the
- <code>_iterator</code> suffix to the member's name, and an alias
- of the constant iterator type with the name created by appending the
- <code>_const_iterator</code> suffix to the member's name.
- </p>
-
- <p>The accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to the
- container and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the container and can
- be used for read-write access.
- </p>
-
- <p>The modifier function expects an argument of type reference to
- constant of the container type. The modifier function
- makes a deep copy of its argument. For instance:
- </p>
-
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="member" type="string" minOccurs="unbounded"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef xml_schema::string member_type;
- typedef sequence&lt;member_type> member_sequence;
- typedef member_sequence::iterator member_iterator;
- typedef member_sequence::const_iterator member_const_iterator;
-
- // Accessors.
- //
- const member_sequence&amp;
- member () const;
-
- member_sequence&amp;
- member ();
-
- // Modifier.
- //
- void
- member (const member_sequence&amp;);
-
- ...
-
-};
- </pre>
-
- <p>The <code>sequence</code> class template is defined in an
- implementation-specific namespace. It conforms to the
- 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>. 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>
- 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
- (<code>std::auto_ptr</code> or <code>std::unique_ptr</code>,
- depending on the C++ standard selected) to the
- element type instead of the constant reference. They assume
- ownership of the pointed to object and reset 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|unique]_ptr&lt;X>)
-
- iterator
- insert (iterator position, std::[auto|unique]_ptr&lt;X>)
-
- std::[auto|unique]_ptr&lt;X>
- detach_back (bool pop = true);
-
- iterator
- detach (iterator position,
- std::[auto|unique]_ptr&lt;X>&amp; result,
- bool erase = true)
-
- ...
-}
- </pre>
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o)
-{
- using xml_schema::string;
-
- object::member_sequence&amp; s (o.member ());
-
- // Iteration.
- //
- for (object::member_iterator i (s.begin ()); i != s.end (); ++i)
- {
- string&amp; value (*i);
- }
-
- // Modification.
- //
- s.push_back ("hello"); // deep copy
-
- // C++98 version.
- //
- std::auto_ptr&lt;string> p (new string ("hello"));
- s.push_back (p); // assumes ownership
- p = s.detach_back (); // detach and pop
- s.push_back (p); // re-append
-
- // C++11 version.
- //
- std::unique_ptr&lt;string> p (new string ("hello"));
- s.push_back (std::move (p)); // assumes ownership
- p = s.detach_back (); // detach and pop
- s.push_back (std::move (p)); // re-append
-
- // Setting a new container.
- //
- object::member_sequence n;
- n.push_back ("one");
- n.push_back ("two");
- o.member (n); // deep copy
-}
- </pre>
-
- <h3><a name="2.8.4">2.8.4 Element Order</a></h3>
-
- <p>C++/Tree is a "flattening" mapping in a sense that many levels of
- nested compositors (<code>choice</code> and <code>sequence</code>),
- all potentially with their own cardinalities, are in the end mapped
- to a flat set of elements with one of the three cardinality classes
- discussed in the previous sections. While this results in a simple
- and easy to use API for most types, in certain cases, the order of
- elements in the actual XML documents is not preserved once parsed
- into the object model. And sometimes such order has
- application-specific significance. As an example, consider a schema
- that defines a batch of bank transactions:</p>
-
- <pre class="xml">
-&lt;complexType name="withdraw">
- &lt;sequence>
- &lt;element name="account" type="unsignedInt"/>
- &lt;element name="amount" type="unsignedInt"/>
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;complexType name="deposit">
- &lt;sequence>
- &lt;element name="account" type="unsignedInt"/>
- &lt;element name="amount" type="unsignedInt"/>
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;complexType name="batch">
- &lt;choice minOccurs="0" maxOccurs="unbounded">
- &lt;element name="withdraw" type="withdraw"/>
- &lt;element name="deposit" type="deposit"/>
- &lt;/choice>
-&lt;/complexType>
- </pre>
-
- <p>The batch can contain any number of transactions in any order
- but the order of transactions in each actual batch is significant.
- For instance, consider what could happen if we reorder the
- transactions and apply all the withdrawals before deposits.</p>
-
- <p>For the <code>batch</code> schema type defined above the default
- C++/Tree mapping will produce a C++ class that contains a pair of
- sequence containers, one for each of the two elements. While this
- will capture the content (transactions), the order of this content
- as it appears in XML will be lost. Also, if we try to serialize the
- batch we just loaded back to XML, all the withdrawal transactions
- will appear before deposits.</p>
-
- <p>To overcome this limitation of a flattening mapping, C++/Tree
- allows us to mark certain XML Schema types, for which content
- order is important, as ordered.</p>
-
- <p>There are several command line options that control which
- schema types are treated as ordered. To make an individual
- type ordered, we use the <code>--ordered-type</code> option,
- for example:</p>
-
- <pre class="term">
---ordered-type batch
- </pre>
-
- <p>To automatically treat all the types that are derived from an ordered
- type also ordered, we use the <code>--ordered-type-derived</code>
- option. This is primarily useful if you would like to iterate
- over the complete hierarchy's content using the content order
- sequence (discussed below).</p>
-
- <p>Ordered types are also useful for handling mixed content. To
- automatically mark all the types with mixed content as ordered
- we use the <code>--ordered-type-mixed</code> option. For more
- information on handling mixed content see <a href="#2.13">Section
- 2.13, "Mapping for Mixed Content Models"</a>.</p>
-
- <p>Finally, we can mark all the types in the schema we are
- compiling with the <code>--ordered-type-all</code> option.
- You should only resort to this option if all the types in
- your schema truly suffer from the loss of content
- order since, as we will discuss shortly, ordered types
- require extra effort to access and, especially, modify.
- See the
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a> for more information on
- these options.</p>
-
- <p>Once a type is marked ordered, C++/Tree alters its mapping
- in several ways. Firstly, for each local element, element
- wildcard (<a href="#2.12.4">Section 2.12.4, "Element Wildcard
- Order"</a>), and mixed content text (<a href="#2.13">Section
- 2.13, "Mapping for Mixed Content Models"</a>) in this type, a
- content id constant is generated. Secondly, an addition sequence
- is added to the class that captures the content order. Here
- is how the mapping of our <code>batch</code> class changes
- once we make it ordered:</p>
-
- <pre class="c++">
-class batch: public xml_schema::type
-{
-public:
- // withdraw
- //
- typedef withdraw withdraw_type;
- typedef sequence&lt;withdraw_type> withdraw_sequence;
- typedef withdraw_sequence::iterator withdraw_iterator;
- typedef withdraw_sequence::const_iterator withdraw_const_iterator;
-
- static const std::size_t withdraw_id = 1;
-
- const withdraw_sequence&amp;
- withdraw () const;
-
- withdraw_sequence&amp;
- withdraw ();
-
- void
- withdraw (const withdraw_sequence&amp;);
-
- // deposit
- //
- typedef deposit deposit_type;
- typedef sequence&lt;deposit_type> deposit_sequence;
- typedef deposit_sequence::iterator deposit_iterator;
- typedef deposit_sequence::const_iterator deposit_const_iterator;
-
- static const std::size_t deposit_id = 2;
-
- const deposit_sequence&amp;
- deposit () const;
-
- deposit_sequence&amp;
- deposit ();
-
- void
- deposit (const deposit_sequence&amp;);
-
- // content_order
- //
- typedef xml_schema::content_order content_order_type;
- typedef std::vector&lt;content_order_type> content_order_sequence;
- typedef content_order_sequence::iterator content_order_iterator;
- typedef content_order_sequence::const_iterator content_order_const_iterator;
-
- const content_order_sequence&amp;
- content_order () const;
-
- content_order_sequence&amp;
- content_order ();
-
- void
- content_order (const content_order_sequence&amp;);
-
- ...
-};
- </pre>
-
- <p>Notice the <code>withdraw_id</code> and <code>deposit_id</code>
- content ids as well as the extra <code>content_order</code>
- sequence that does not correspond to any element in the
- schema definition. The other changes to the mapping for ordered
- types has to do with XML parsing and serialization code. During
- parsing the content order is captured in the <code>content_order</code>
- sequence while during serialization this sequence is used to
- determine the order in which content is serialized. The
- <code>content_order</code> sequence is also copied during
- copy construction and assigned during copy assignment. It is also
- taken into account during comparison.</p>
-
- <p>The entry type of the <code>content_order</code> sequence is the
- <code>xml_schema::content_order</code> type that has the following
- interface:</p>
-
- <pre class="c++">
-namespace xml_schema
-{
- struct content_order
- {
- content_order (std::size_t id, std::size_t index = 0);
-
- std::size_t id;
- std::size_t index;
- };
-
- bool
- operator== (const content_order&amp;, const content_order&amp;);
-
- bool
- operator!= (const content_order&amp;, const content_order&amp;);
-
- bool
- operator&lt; (const content_order&amp;, const content_order&amp;);
-}
- </pre>
-
- <p>The <code>content_order</code> sequence describes the order of
- content (elements, including wildcards, as well as mixed content
- text). Each entry in this sequence consists of the content id
- (for example, <code>withdraw_id</code> or <code>deposit_id</code>
- in our case) as well as, for elements of the sequence cardinality
- class, an index into the corresponding sequence container (the
- index is unused for the one and optional cardinality classes).
- For example, in our case, if the content id is <code>withdraw_id</code>,
- then the index will point into the <code>withdraw</code> element
- sequence.</p>
-
- <p>With all this information we can now examine how to iterate over
- transaction in the batch in content order:</p>
-
- <pre class="c++">
-batch&amp; b = ...
-
-for (batch::content_order_const_iterator i (b.content_order ().begin ());
- i != b.content_order ().end ();
- ++i)
-{
- switch (i->id)
- {
- case batch::withdraw_id:
- {
- const withdraw&amp; t (b.withdraw ()[i->index]);
- cerr &lt;&lt; t.account () &lt;&lt; " withdraw " &lt;&lt; t.amount () &lt;&lt; endl;
- break;
- }
- case batch::deposit_id:
- {
- const deposit&amp; t (b.deposit ()[i->index]);
- cerr &lt;&lt; t.account () &lt;&lt; " deposit " &lt;&lt; t.amount () &lt;&lt; endl;
- break;
- }
- default:
- {
- assert (false); // Unknown content id.
- }
- }
-}
- </pre>
-
- <p>If we serialized our batch back to XML, we would also see that the
- order of transactions in the output is exactly the same as in the
- input rather than all the withdrawals first followed by all the
- deposits.</p>
-
- <p>The most complex aspect of working with ordered types is
- modifications. Now we not only need to change the content,
- but also remember to update the order information corresponding
- to this change. As a first example, we add a deposit transaction
- to the batch:</p>
-
- <pre class="c++">
-using xml_schema::content_order;
-
-batch::deposit_sequence&amp; d (b.deposit ());
-batch::withdraw_sequence&amp; w (b.withdraw ());
-batch::content_order_sequence&amp; co (b.content_order ());
-
-d.push_back (deposit (123456789, 100000));
-co.push_back (content_order (batch::deposit_id, d.size () - 1));
- </pre>
-
- <p>In the above example we first added the content (deposit
- transaction) and then updated the content order information
- by adding an entry with <code>deposit_id</code> content
- id and the index of the just added deposit transaction.</p>
-
- <p>Removing the last transaction can be easy if we know which
- transaction (deposit or withdrawal) is last:</p>
-
- <pre class="c++">
-d.pop_back ();
-co.pop_back ();
- </pre>
-
- <p>If, however, we do not know which transaction is last, then
- things get a bit more complicated:</p>
-
- <pre class="c++">
-switch (co.back ().id)
-{
-case batch::withdraw_id:
- {
- d.pop_back ();
- break;
- }
-case batch::deposit_id:
- {
- w.pop_back ();
- break;
- }
-}
-
-co.pop_back ();
- </pre>
-
- <p>The following example shows how to add a transaction at the
- beginning of the batch:</p>
-
- <pre class="c++">
-w.push_back (withdraw (123456789, 100000));
-co.insert (co.begin (),
- content_order (batch::withdraw_id, w.size () - 1));
- </pre>
-
- <p>Note also that when we merely modify the content of one
- of the elements in place, we do not need to update its
- order since it doesn't change. For example, here is how
- we can change the amount in the first withdrawal:</p>
-
- <pre class="c++">
-w[0].amount (10000);
- </pre>
-
- <p>For the complete working code shown in this section refer to the
- <code>order/element</code> example in the
- <code>examples/cxx/tree/</code> directory in the XSD distribution.</p>
-
- <p>If both the base and derived types are ordered, then the
- content order sequence is only added to the base and the content
- ids are unique within the whole hierarchy. In this case
- the content order sequence for the derived type contains
- ordering information for both base and derived content.</p>
-
- <p>In some applications we may need to perform more complex
- content processing. For example, in our case, we may need
- to remove all the withdrawal transactions. The default
- container, <code>std::vector</code>, is not particularly
- suitable for such operations. What may be required by
- some applications is a multi-index container that not
- only allows us to iterate in content order similar to
- <code>std::vector</code> but also search by the content
- id as well as the content id and index pair.</p>
-
- <p>While C++/Tree does not provide this functionality by
- default, it allows us to specify a custom container
- type for content order with the <code>--order-container</code>
- command line option. The only requirement from the
- generated code side for such a container is to provide
- the <code>vector</code>-like <code>push_back()</code>,
- <code>size()</code>, and const iteration interfaces.</p>
-
- <p>As an example, here is how we can use the Boost Multi-Index
- container for content order. First we create the
- <code>content-order-container.hxx</code> header with the
- following definition (in C++11, use the alias template
- instead):</p>
-
- <pre class="c++">
-#ifndef CONTENT_ORDER_CONTAINER
-#define CONTENT_ORDER_CONTAINER
-
-#include &lt;cstddef> // std::size_t
-
-#include &lt;boost/multi_index_container.hpp>
-#include &lt;boost/multi_index/member.hpp>
-#include &lt;boost/multi_index/identity.hpp>
-#include &lt;boost/multi_index/ordered_index.hpp>
-#include &lt;boost/multi_index/random_access_index.hpp>
-
-struct by_id {};
-struct by_id_index {};
-
-template &lt;typename T>
-struct content_order_container:
- boost::multi_index::multi_index_container&lt;
- T,
- boost::multi_index::indexed_by&lt;
- boost::multi_index::random_access&lt;>,
- boost::multi_index::ordered_unique&lt;
- boost::multi_index::tag&lt;by_id_index>,
- boost::multi_index::identity&lt;T>
- >,
- boost::multi_index::ordered_non_unique&lt;
- boost::multi_index::tag&lt;by_id>,
- boost::multi_index::member&lt;T, std::size_t, &amp;T::id>
- >
- >
- >
-{};
-
-#endif
- </pre>
-
- <p>Next we add the following two XSD compiler options to include
- this header into every generated header file and to use the
- custom container type (see the XSD compiler command line manual
- for more information on shell quoting for the first option):</p>
-
- <pre class="term">
---hxx-prologue '#include "content-order-container.hxx"'
---order-container content_order_container
- </pre>
-
- <p>With these changes we can now use the multi-index functionality,
- for example, to search for a specific content id:</p>
-
- <pre class="c++">
-typedef batch::content_order_sequence::index&lt;by_id>::type id_set;
-typedef id_set::iterator id_iterator;
-
-const id_set&amp; ids (b.content_order ().get&lt;by_id> ());
-
-std::pair&lt;id_iterator, id_iterator> r (
- ids.equal_range (std::size_t (batch::deposit_id));
-
-for (id_iterator i (r.first); i != r.second; ++i)
-{
- const deposit&amp; t (b.deposit ()[i->index]);
- cerr &lt;&lt; t.account () &lt;&lt; " deposit " &lt;&lt; t.amount () &lt;&lt; endl;
-}
- </pre>
-
- <h2><a name="2.9">2.9 Mapping for Global Elements</a></h2>
-
- <p>An XML Schema element definition is called global if it appears
- directly under the <code>schema</code> element.
- A global element is a valid root of an instance document. By
- default, a global element is mapped to a set of overloaded
- parsing and, optionally, serialization functions with the
- same name as the element. It is also possible to generate types
- for root elements instead of parsing and serialization functions.
- This is primarily useful to distinguish object models with the
- same root type but with different root elements. See
- <a href="#2.9.1">Section 2.9.1, "Element Types"</a> for details.
- It is also possible to request the generation of an element map
- which allows uniform parsing and serialization of multiple root
- elements. See <a href="#2.9.2">Section 2.9.2, "Element Map"</a>
- for details.
- </p>
-
- <p>The parsing functions read XML instance documents and return
- corresponding object models as an automatic pointer
- (<code>std::auto_ptr</code> or <code>std::unique_ptr</code>,
- depending on the C++ standard selected). Their signatures
- have the following pattern (<code>type</code> denotes
- element's type and <code>name</code> denotes element's
- name):
- </p>
-
- <pre class="c++">
-std::[auto|unique]_ptr&lt;type>
-name (....);
- </pre>
-
- <p>The process of parsing, including the exact signatures of the parsing
- functions, is the subject of <a href="#3">Chapter 3, "Parsing"</a>.
- </p>
-
- <p>The serialization functions write object models back to XML instance
- documents. Their signatures have the following pattern:
- </p>
-
- <pre class="c++">
-void
-name (&lt;stream type>&amp;, const type&amp;, ....);
- </pre>
-
- <p>The process of serialization, including the exact signatures of the
- serialization functions, is the subject of <a href="#4">Chapter 4,
- "Serialization"</a>.
- </p>
-
-
- <h3><a name="2.9.1">2.9.1 Element Types</a></h3>
-
- <p>The generation of element types is requested with the
- <code>--generate-element-type</code> option. With this option
- each global element is mapped to a C++ class with the
- same name as the element. Such a class is derived from
- <code>xml_schema::element_type</code> and contains the same set
- of type definitions, constructors, and member function as would a
- type containing a single element with the One cardinality class
- named <code>"value"</code>. In addition, the element type also
- contains a set of member functions for accessing the element
- name and namespace as well as its value in a uniform manner.
- For example:</p>
-
- <pre class="xml">
-&lt;complexType name="type">
- &lt;sequence>
- ...
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;element name="root" type="type"/>
- </pre>
-
-<p>is mapped to:</p>
-
- <pre class="c++">
-class type
-{
- ...
-};
-
-class root: public xml_schema::element_type
-{
-public:
- // Element value.
- //
- typedef type value_type;
-
- const value_type&amp;
- value () const;
-
- value_type&amp;
- value ();
-
- void
- value (const value_type&amp;);
-
- void
- value (std::[auto|unique]_ptr&lt;value_type>);
-
- // Constructors.
- //
- root (const value_type&amp;);
-
- root (std::[auto|unique]_ptr&lt;value_type>);
-
- root (const xercesc::DOMElement&amp;, xml_schema::flags = 0);
-
- root (const root&amp;, xml_schema::flags = 0);
-
- virtual root*
- _clone (xml_schema::flags = 0) const;
-
- // Element name and namespace.
- //
- static const std::string&amp;
- name ();
-
- static const std::string&amp;
- namespace_ ();
-
- virtual const std::string&amp;
- _name () const;
-
- virtual const std::string&amp;
- _namespace () const;
-
- // Element value as xml_schema::type.
- //
- virtual const xml_schema::type*
- _value () const;
-
- virtual xml_schema::type*
- _value ();
-};
-
-void
-operator&lt;&lt; (xercesc::DOMElement&amp;, const root&amp;);
- </pre>
-
- <p>The <code>xml_schema::element_type</code> class is a common
- base type for all element types and is defined as follows:</p>
-
- <pre class="c++">
-namespace xml_schema
-{
- class element_type
- {
- public:
- virtual
- ~element_type ();
-
- virtual element_type*
- _clone (flags f = 0) const = 0;
-
- virtual const std::basic_string&lt;C>&amp;
- _name () const = 0;
-
- virtual const std::basic_string&lt;C>&amp;
- _namespace () const = 0;
-
- virtual xml_schema::type*
- _value () = 0;
-
- virtual const xml_schema::type*
- _value () const = 0;
- };
-}
- </pre>
-
- <p>The <code>_value()</code> member function returns a pointer to
- the element value or 0 if the element is of a fundamental C++
- type and therefore is not derived from <code>xml_schema::type</code>.
- </p>
-
- <p>Unlike parsing and serialization functions, element types
- are only capable of parsing and serializing from/to a
- <code>DOMElement</code> object. This means that the application
- will need to perform its own XML-to-DOM parsing and DOM-to-XML
- serialization. The following section describes a mechanism
- provided by the mapping to uniformly parse and serialize
- multiple root elements.</p>
-
-
- <h3><a name="2.9.2">2.9.2 Element Map</a></h3>
-
- <p>When element types are generated for root elements it is also
- possible to request the generation of an element map with the
- <code>--generate-element-map</code> option. The element map
- allows uniform parsing and serialization of multiple root
- elements via the common <code>xml_schema::element_type</code>
- base type. The <code>xml_schema::element_map</code> class is
- defined as follows:</p>
-
- <pre class="c++">
-namespace xml_schema
-{
- class element_map
- {
- public:
- static std::[auto|unique]_ptr&lt;xml_schema::element_type>
- parse (const xercesc::DOMElement&amp;, flags = 0);
-
- static void
- serialize (xercesc::DOMElement&amp;, const element_type&amp;);
- };
-}
- </pre>
-
- <p>The <code>parse()</code> function creates the corresponding
- element type object based on the element name and namespace
- and returns it as an automatic pointer (<code>std::auto_ptr</code>
- or <code>std::unique_ptr</code>, depending on the C++ standard
- selected) to <code>xml_schema::element_type</code>.
- The <code>serialize()</code> function serializes the passed element
- object to <code>DOMElement</code>. Note that in case of
- <code>serialize()</code>, the <code>DOMElement</code> object
- should have the correct name and namespace. If no element type is
- available for an element, both functions throw the
- <code>xml_schema::no_element_info</code> exception:</p>
-
- <pre class="c++">
-struct no_element_info: virtual exception
-{
- no_element_info (const std::basic_string&lt;C>&amp; element_name,
- const std::basic_string&lt;C>&amp; element_namespace);
-
- const std::basic_string&lt;C>&amp;
- element_name () const;
-
- const std::basic_string&lt;C>&amp;
- element_namespace () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The application can discover the actual type of the element
- object returned by <code>parse()</code> either using
- <code>dynamic_cast</code> or by comparing element names and
- namespaces. The following code fragments illustrate how the
- element map can be used:</p>
-
- <pre class="c++">
-// Parsing.
-//
-DOMElement&amp; e = ... // Parse XML to DOM.
-
-auto_ptr&lt;xml_schema::element_type> r (
- xml_schema::element_map::parse (e));
-
-if (root1 r1 = dynamic_cast&lt;root1*> (r.get ()))
-{
- ...
-}
-else if (r->_name == root2::name () &amp;&amp;
- r->_namespace () == root2::namespace_ ())
-{
- root2&amp; r2 (static_cast&lt;root2&amp;> (*r));
-
- ...
-}
- </pre>
-
- <pre class="c++">
-// Serialization.
-//
-xml_schema::element_type&amp; r = ...
-
-string name (r._name ());
-string ns (r._namespace ());
-
-DOMDocument&amp; doc = ... // Create a new DOMDocument with name and ns.
-DOMElement&amp; e (*doc->getDocumentElement ());
-
-xml_schema::element_map::serialize (e, r);
-
-// Serialize DOMDocument to XML.
- </pre>
-
- <!-- -->
-
- <h2><a name="2.10">2.10 Mapping for Global Attributes</a></h2>
-
- <p>An XML Schema attribute definition is called global if it appears
- directly under the <code>schema</code> element. A global
- attribute does not have any mapping.
- </p>
-
- <!--
- When it is referenced from
- a local attribute definition (using the <code>ref</code> attribute)
- it is treated as a local attribute (see Section 2.8, "Mapping for
- Local Elements and Attributes").
- -->
-
- <h2><a name="2.11">2.11 Mapping for <code>xsi:type</code> and Substitution
- Groups</a></h2>
-
- <p>The mapping provides optional support for the XML Schema polymorphism
- features (<code>xsi:type</code> and substitution groups) which can
- be requested with the <code>--generate-polymorphic</code> option.
- When used, the dynamic type of a member may be different from
- its static type. Consider the following schema definition and
- instance document:
- </p>
-
- <pre class="xml">
-&lt;!-- test.xsd -->
-&lt;schema>
- &lt;complexType name="base">
- &lt;attribute name="text" type="string"/>
- &lt;/complexType>
-
- &lt;complexType name="derived">
- &lt;complexContent>
- &lt;extension base="base">
- &lt;attribute name="extra-text" type="string"/>
- &lt;/extension>
- &lt;/complexContent>
- &lt;/complexType>
-
- &lt;complexType name="root_type">
- &lt;sequence>
- &lt;element name="item" type="base" maxOccurs="unbounded"/>
- &lt;/sequence>
- &lt;/complexType>
-
- &lt;element name="root" type="root_type"/>
-&lt;/schema>
-
-&lt;!-- test.xml -->
-&lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- &lt;item text="hello"/>
- &lt;item text="hello" extra-text="world" xsi:type="derived"/>
-&lt;/root>
- </pre>
-
- <p>In the resulting object model, the container for
- the <code>root::item</code> member will have two elements:
- the first element's type will be <code>base</code> while
- the second element's (dynamic) type will be
- <code>derived</code>. This can be discovered using the
- <code>dynamic_cast</code> operator as shown in the following
- example:
- </p>
-
- <pre class="c++">
-void
-f (root&amp; r)
-{
- for (root::item_const_iterator i (r.item ().begin ());
- i != r.item ().end ()
- ++i)
- {
- if (derived* d = dynamic_cast&lt;derived*> (&amp;(*i)))
- {
- // derived
- }
- else
- {
- // base
- }
- }
-}
- </pre>
-
- <p>The <code>_clone</code> virtual function should be used instead of
- copy constructors to make copies of members that might use
- polymorphism:
- </p>
-
- <pre class="c++">
-void
-f (root&amp; r)
-{
- for (root::item_const_iterator i (r.item ().begin ());
- i != r.item ().end ()
- ++i)
- {
- std::auto_ptr&lt;base> c (i->_clone ());
- }
-}
- </pre>
-
- <p>The mapping can often automatically determine which types are
- polymorphic based on the substitution group declarations. However,
- if your XML vocabulary is not using substitution groups or if
- substitution groups are defined in a separate schema, then you will
- need to use the <code>--polymorphic-type</code> option to specify
- which types are polymorphic. When using this option you only need
- to specify the root of a polymorphic type hierarchy and the mapping
- will assume that all the derived types are also polymorphic.
- Also note that you need to specify this option when compiling every
- schema file that references the polymorphic type. Consider the following
- two schemas as an example:</p>
-
- <pre class="xml">
-&lt;!-- base.xsd -->
-&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
- &lt;xs:complexType name="base">
- &lt;xs:sequence>
- &lt;xs:element name="b" type="xs:int"/>
- &lt;/xs:sequence>
- &lt;/xs:complexType>
-
- &lt;!-- substitution group root -->
- &lt;xs:element name="base" type="base"/>
-
-&lt;/xs:schema>
- </pre>
-
- <pre class="xml">
-&lt;!-- derived.xsd -->
-&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
- &lt;include schemaLocation="base.xsd"/>
-
- &lt;xs:complexType name="derived">
- &lt;xs:complexContent>
- &lt;xs:extension base="base">
- &lt;xs:sequence>
- &lt;xs:element name="d" type="xs:string"/>
- &lt;/xs:sequence>
- &lt;/xs:extension>
- &lt;/xs:complexContent>
- &lt;/xs:complexType>
-
- &lt;xs:element name="derived" type="derived" substitutionGroup="base"/>
-
-&lt;/xs:schema>
- </pre>
-
- <p>In this example we need to specify "<code>--polymorphic-type base</code>"
- when compiling both schemas because the substitution group is declared
- in a schema other than the one defining type <code>base</code>.</p>
-
- <p>You can also indicate that all types should be treated as polymorphic
- with the <code>--polymorphic-type-all</code>. However, this may result
- in slower generated code with a greater footprint.</p>
-
-
- <!-- Mapping for any and anyAttribute -->
-
-
- <h2><a name="2.12">2.12 Mapping for <code>any</code> and <code>anyAttribute</code></a></h2>
-
- <p>For the XML Schema <code>any</code> and <code>anyAttribute</code>
- wildcards an optional mapping can be requested with the
- <code>--generate-wildcard</code> option. The mapping represents
- the content matched by wildcards as DOM fragments. Because the
- DOM API is used to access such content, the Xerces-C++ runtime
- should be initialized by the application prior to parsing and
- should remain initialized for the lifetime of objects with
- the wildcard content. For more information on the Xerces-C++
- runtime initialization see <a href="#3.1">Section 3.1,
- "Initializing the Xerces-C++ Runtime"</a>.
- </p>
-
- <p>The mapping for <code>any</code> is similar to the mapping for
- local elements (see <a href="#2.8">Section 2.8, "Mapping for Local
- Elements and Attributes"</a>) except that the type used in the
- wildcard mapping is <code>xercesc::DOMElement</code>. As with local
- elements, the mapping divides all possible cardinality combinations
- into three cardinality classes: <i>one</i>, <i>optional</i>, and
- <i>sequence</i>.
- </p>
-
- <p>The mapping for <code>anyAttribute</code> represents the attributes
- matched by this wildcard as a set of <code>xercesc::DOMAttr</code>
- objects with a key being the attribute's name and namespace.</p>
-
- <p>Similar to local elements and attributes, the <code>any</code> and
- <code>anyAttribute</code> wildcards are mapped to a set of public type
- definitions (typedefs) and a set of public accessor and modifier
- functions. Type definitions have names derived from <code>"any"</code>
- for the <code>any</code> wildcard and <code>"any_attribute"</code>
- for the <code>anyAttribute</code> wildcard. The accessor and modifier
- functions are named <code>"any"</code> for the <code>any</code> wildcard
- and <code>"any_attribute"</code> for the <code>anyAttribute</code>
- wildcard. Subsequent wildcards in the same type have escaped names
- such as <code>"any1"</code> or <code>"any_attribute1"</code>.
- </p>
-
- <p>Because Xerces-C++ DOM nodes always belong to a <code>DOMDocument</code>,
- each type with a wildcard has an associated <code>DOMDocument</code>
- object. The reference to this object can be obtained using the accessor
- function called <code>dom_document</code>. The access to the document
- object from the application code may be necessary to create or modify
- the wildcard content. For example:
- </p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;any namespace="##other"/>
- &lt;/sequence>
- &lt;anyAttribute namespace="##other"/>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // any
- //
- const xercesc::DOMElement&amp;
- any () const;
-
- void
- any (const xercesc::DOMElement&amp;);
-
- ...
-
- // any_attribute
- //
- typedef attribute_set any_attribute_set;
- typedef any_attribute_set::iterator any_attribute_iterator;
- typedef any_attribute_set::const_iterator any_attribute_const_iterator;
-
- const any_attribute_set&amp;
- any_attribute () const;
-
- any_attribute_set&amp;
- any_attribute ();
-
- ...
-
- // DOMDocument object for wildcard content.
- //
- const xercesc::DOMDocument&amp;
- dom_document () const;
-
- xercesc::DOMDocument&amp;
- dom_document ();
-
- ...
-};
- </pre>
-
-
- <p>Names and semantics of type definitions for the wildcards as well
- as signatures of the accessor and modifier functions depend on the
- wildcard type as well as the cardinality class for the <code>any</code>
- wildcard. They are described in the following sub-sections.
- </p>
-
-
- <h3><a name="2.12.1">2.12.1 Mapping for <code>any</code> with the One Cardinality Class</a></h3>
-
- <p>For <code>any</code> with the One cardinality class,
- there are no type definitions. The accessor functions come in
- constant and non-constant versions. The constant accessor function
- returns a constant reference to <code>xercesc::DOMElement</code> and
- can be used for read-only access. The non-constant version returns
- an unrestricted reference to <code>xercesc::DOMElement</code> and can
- be used for read-write access.
- </p>
-
- <p>The first modifier function expects an argument of type reference
- to constant <code>xercesc::DOMElement</code> and makes a deep copy
- of its argument. The second modifier function expects an argument of
- type pointer to <code>xercesc::DOMElement</code>. This modifier
- function assumes ownership of its argument and expects the element
- object to be created using the DOM document associated with this
- instance. For example:
- </p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;any namespace="##other"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Accessors.
- //
- const xercesc::DOMElement&amp;
- any () const;
-
- xercesc::DOMElement&amp;
- any ();
-
- // Modifiers.
- //
- void
- any (const xercesc::DOMElement&amp;);
-
- void
- any (xercesc::DOMElement*);
-
- ...
-
-};
- </pre>
-
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o, const xercesc::DOMElement&amp; e)
-{
- using namespace xercesc;
-
- DOMElement&amp; e1 (o.any ()); // get
- o.any (e) // set, deep copy
- DOMDocument&amp; doc (o.dom_document ());
- o.any (doc.createElement (...)); // set, assumes ownership
-}
- </pre>
-
- <h3><a name="2.12.2">2.12.2 Mapping for <code>any</code> with the Optional Cardinality Class</a></h3>
-
- <p>For <code>any</code> with the Optional cardinality class, the type
- definitions consist of an alias for the container type with name
- <code>any_optional</code> (or <code>any1_optional</code>, etc., for
- subsequent wildcards in the type definition).
- </p>
-
- <p>Unlike accessor functions for the One cardinality class, accessor
- functions for the Optional cardinality class return references to
- corresponding containers rather than directly to <code>DOMElement</code>.
- The accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to
- the container and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the container
- and can be used for read-write access.
- </p>
-
- <p>The modifier functions are overloaded for <code>xercesc::DOMElement</code>
- and the container type. The first modifier function expects an argument of
- type reference to constant <code>xercesc::DOMElement</code> and
- makes a deep copy of its argument. The second modifier function
- expects an argument of type pointer to <code>xercesc::DOMElement</code>.
- This modifier function assumes ownership of its argument and expects
- the element object to be created using the DOM document associated
- with this instance. The third modifier function expects an argument
- of type reference to constant of the container type and makes a
- deep copy of its argument. For instance:
- </p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;any namespace="##other" minOccurs="0"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef element_optional any_optional;
-
- // Accessors.
- //
- const any_optional&amp;
- any () const;
-
- any_optional&amp;
- any ();
-
- // Modifiers.
- //
- void
- any (const xercesc::DOMElement&amp;);
-
- void
- any (xercesc::DOMElement*);
-
- void
- any (const any_optional&amp;);
-
- ...
-
-};
- </pre>
-
-
- <p>The <code>element_optional</code> container is a
- specialization of the <code>optional</code> class template described
- in <a href="#2.8.2">Section 2.8.2, "Mapping for Members with the Optional
- Cardinality Class"</a>. Its interface is presented below:
- </p>
-
- <pre class="c++">
-class element_optional
-{
-public:
- explicit
- element_optional (xercesc::DOMDocument&amp;);
-
- // Makes a deep copy.
- //
- element_optional (const xercesc::DOMElement&amp;, xercesc::DOMDocument&amp;);
-
- // Assumes ownership.
- //
- element_optional (xercesc::DOMElement*, xercesc::DOMDocument&amp;);
-
- element_optional (const element_optional&amp;, xercesc::DOMDocument&amp;);
-
-public:
- element_optional&amp;
- operator= (const xercesc::DOMElement&amp;);
-
- element_optional&amp;
- operator= (const element_optional&amp;);
-
- // Pointer-like interface.
- //
-public:
- const xercesc::DOMElement*
- operator-> () const;
-
- xercesc::DOMElement*
- operator-> ();
-
- const xercesc::DOMElement&amp;
- operator* () const;
-
- xercesc::DOMElement&amp;
- operator* ();
-
- typedef void (element_optional::*bool_convertible) ();
- operator bool_convertible () const;
-
- // Get/set interface.
- //
-public:
- bool
- present () const;
-
- const xercesc::DOMElement&amp;
- get () const;
-
- xercesc::DOMElement&amp;
- get ();
-
- // Makes a deep copy.
- //
- void
- set (const xercesc::DOMElement&amp;);
-
- // Assumes ownership.
- //
- void
- set (xercesc::DOMElement*);
-
- void
- reset ();
-};
-
-bool
-operator== (const element_optional&amp;, const element_optional&amp;);
-
-bool
-operator!= (const element_optional&amp;, const element_optional&amp;);
- </pre>
-
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o, const xercesc::DOMElement&amp; e)
-{
- using namespace xercesc;
-
- DOMDocument&amp; doc (o.dom_document ());
-
- if (o.any ().present ()) // test
- {
- DOMElement&amp; e1 (o.any ().get ()); // get
- o.any ().set (e); // set, deep copy
- o.any ().set (doc.createElement (...)); // set, assumes ownership
- o.any ().reset (); // reset
- }
-
- // Same as above but using pointer notation:
- //
- if (o.member ()) // test
- {
- DOMElement&amp; e1 (*o.any ()); // get
- o.any (e); // set, deep copy
- o.any (doc.createElement (...)); // set, assumes ownership
- o.any ().reset (); // reset
- }
-}
- </pre>
-
-
-
- <h3><a name="2.12.3">2.12.3 Mapping for <code>any</code> with the Sequence Cardinality Class</a></h3>
-
- <p>For <code>any</code> with the Sequence cardinality class, the type
- definitions consist of an alias of the container type with name
- <code>any_sequence</code> (or <code>any1_sequence</code>, etc., for
- subsequent wildcards in the type definition), an alias of the iterator
- type with name <code>any_iterator</code> (or <code>any1_iterator</code>,
- etc., for subsequent wildcards in the type definition), and an alias
- of the constant iterator type with name <code>any_const_iterator</code>
- (or <code>any1_const_iterator</code>, etc., for subsequent wildcards
- in the type definition).
- </p>
-
- <p>The accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to the
- container and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the container and can
- be used for read-write access.
- </p>
-
- <p>The modifier function expects an argument of type reference to
- constant of the container type. The modifier function makes
- a deep copy of its argument. For instance:
- </p>
-
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;any namespace="##other" minOccurs="unbounded"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef element_sequence any_sequence;
- typedef any_sequence::iterator any_iterator;
- typedef any_sequence::const_iterator any_const_iterator;
-
- // Accessors.
- //
- const any_sequence&amp;
- any () const;
-
- any_sequence&amp;
- any ();
-
- // Modifier.
- //
- void
- any (const any_sequence&amp;);
-
- ...
-
-};
- </pre>
-
- <p>The <code>element_sequence</code> container is a
- specialization of the <code>sequence</code> class template described
- in <a href="#2.8.3">Section 2.8.3, "Mapping for Members with the
- Sequence Cardinality Class"</a>. Its interface is similar to
- the sequence interface as defined by the ISO/ANSI Standard for
- C++ (ISO/IEC 14882:1998, Section 23.1.1, "Sequences") and is
- presented below:
- </p>
-
- <pre class="c++">
-class element_sequence
-{
-public:
- typedef xercesc::DOMElement value_type;
- typedef xercesc::DOMElement* pointer;
- typedef const xercesc::DOMElement* const_pointer;
- typedef xercesc::DOMElement&amp; reference;
- typedef const xercesc::DOMElement&amp; const_reference;
-
- typedef &lt;implementation-defined> iterator;
- typedef &lt;implementation-defined> const_iterator;
- typedef &lt;implementation-defined> reverse_iterator;
- typedef &lt;implementation-defined> const_reverse_iterator;
-
- typedef &lt;implementation-defined> size_type;
- typedef &lt;implementation-defined> difference_type;
- typedef &lt;implementation-defined> allocator_type;
-
-public:
- explicit
- element_sequence (xercesc::DOMDocument&amp;);
-
- // DOMElement cannot be default-constructed.
- //
- // explicit
- // element_sequence (size_type n);
-
- element_sequence (size_type n,
- const xercesc::DOMElement&amp;,
- xercesc::DOMDocument&amp;);
-
- template &lt;typename I>
- element_sequence (const I&amp; begin,
- const I&amp; end,
- xercesc::DOMDocument&amp;);
-
- element_sequence (const element_sequence&amp;, xercesc::DOMDocument&amp;);
-
- element_sequence&amp;
- operator= (const element_sequence&amp;);
-
-public:
- void
- assign (size_type n, const xercesc::DOMElement&amp;);
-
- template &lt;typename I>
- void
- assign (const I&amp; begin, const I&amp; end);
-
-public:
- // This version of resize can only be used to shrink the
- // sequence because DOMElement cannot be default-constructed.
- //
- void
- resize (size_type);
-
- void
- resize (size_type, const xercesc::DOMElement&amp;);
-
-public:
- size_type
- size () const;
-
- size_type
- max_size () const;
-
- size_type
- capacity () const;
-
- bool
- empty () const;
-
- void
- reserve (size_type);
-
- void
- clear ();
-
-public:
- const_iterator
- begin () const;
-
- const_iterator
- end () const;
-
- iterator
- begin ();
-
- iterator
- end ();
-
- const_reverse_iterator
- rbegin () const;
-
- const_reverse_iterator
- rend () const
-
- reverse_iterator
- rbegin ();
-
- reverse_iterator
- rend ();
-
-public:
- xercesc::DOMElement&amp;
- operator[] (size_type);
-
- const xercesc::DOMElement&amp;
- operator[] (size_type) const;
-
- xercesc::DOMElement&amp;
- at (size_type);
-
- const xercesc::DOMElement&amp;
- at (size_type) const;
-
- xercesc::DOMElement&amp;
- front ();
-
- const xercesc::DOMElement&amp;
- front () const;
-
- xercesc::DOMElement&amp;
- back ();
-
- const xercesc::DOMElement&amp;
- back () const;
-
-public:
- // Makes a deep copy.
- //
- void
- push_back (const xercesc::DOMElement&amp;);
-
- // Assumes ownership.
- //
- void
- push_back (xercesc::DOMElement*);
-
- void
- pop_back ();
-
- // Makes a deep copy.
- //
- iterator
- insert (iterator position, const xercesc::DOMElement&amp;);
-
- // Assumes ownership.
- //
- iterator
- insert (iterator position, xercesc::DOMElement*);
-
- void
- insert (iterator position, size_type n, const xercesc::DOMElement&amp;);
-
- template &lt;typename I>
- void
- insert (iterator position, const I&amp; begin, const I&amp; end);
-
- iterator
- erase (iterator position);
-
- iterator
- erase (iterator begin, iterator end);
-
-public:
- // Note that the DOMDocument object of the two sequences being
- // swapped should be the same.
- //
- void
- swap (sequence&amp; x);
-};
-
-inline bool
-operator== (const element_sequence&amp;, const element_sequence&amp;);
-
-inline bool
-operator!= (const element_sequence&amp;, const element_sequence&amp;);
- </pre>
-
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o, const xercesc::DOMElement&amp; e)
-{
- using namespace xercesc;
-
- object::any_sequence&amp; s (o.any ());
-
- // Iteration.
- //
- for (object::any_iterator i (s.begin ()); i != s.end (); ++i)
- {
- DOMElement&amp; e (*i);
- }
-
- // Modification.
- //
- s.push_back (e); // deep copy
- DOMDocument&amp; doc (o.dom_document ());
- s.push_back (doc.createElement (...)); // assumes ownership
-}
- </pre>
-
- <h3><a name="2.12.4">2.12.4 Element Wildcard Order</a></h3>
-
- <p>Similar to elements, element wildcards in ordered types
- (<a href="#2.8.4">Section 2.8.4, "Element Order"</a>) are assigned
- content ids and are included in the content order sequence.
- Continuing with the bank transactions example started in Section
- 2.8.4, we can extend the batch by allowing custom transactions:</p>
-
- <pre class="xml">
-&lt;complexType name="batch">
- &lt;choice minOccurs="0" maxOccurs="unbounded">
- &lt;element name="withdraw" type="withdraw"/>
- &lt;element name="deposit" type="deposit"/>
- &lt;any namespace="##other" processContents="lax"/>
- &lt;/choice>
-&lt;/complexType>
- </pre>
-
- <p>This will lead to the following changes in the generated
- <code>batch</code> C++ class:</p>
-
- <pre class="c++">
-class batch: public xml_schema::type
-{
-public:
- ...
-
- // any
- //
- typedef element_sequence any_sequence;
- typedef any_sequence::iterator any_iterator;
- typedef any_sequence::const_iterator any_const_iterator;
-
- static const std::size_t any_id = 3UL;
-
- const any_sequence&amp;
- any () const;
-
- any_sequence&amp;
- any ();
-
- void
- any (const any_sequence&amp;);
-
- ...
-};
- </pre>
-
- <p>With this change we also need to update the iteration code to handle
- the new content id:</p>
-
- <pre class="c++">
-for (batch::content_order_const_iterator i (b.content_order ().begin ());
- i != b.content_order ().end ();
- ++i)
-{
- switch (i->id)
- {
- ...
-
- case batch::any_id:
- {
- const DOMElement&amp; e (b.any ()[i->index]);
- ...
- break;
- }
-
- ...
- }
-}
- </pre>
-
- <p>For the complete working code that shows the use of wildcards in
- ordered types refer to the <code>order/element</code> example in
- the <code>examples/cxx/tree/</code> directory in the XSD
- distribution.</p>
-
- <h3><a name="2.12.5">2.12.5 Mapping for <code>anyAttribute</code></a></h3>
-
- <p>For <code>anyAttribute</code> the type definitions consist of an alias
- of the container type with name <code>any_attribute_set</code>
- (or <code>any1_attribute_set</code>, etc., for subsequent wildcards
- in the type definition), an alias of the iterator type with name
- <code>any_attribute_iterator</code> (or <code>any1_attribute_iterator</code>,
- etc., for subsequent wildcards in the type definition), and an alias
- of the constant iterator type with name <code>any_attribute_const_iterator</code>
- (or <code>any1_attribute_const_iterator</code>, etc., for subsequent
- wildcards in the type definition).
- </p>
-
- <p>The accessor functions come in constant and non-constant versions.
- The constant accessor function returns a constant reference to the
- container and can be used for read-only access. The non-constant
- version returns an unrestricted reference to the container and can
- be used for read-write access.
- </p>
-
- <p>The modifier function expects an argument of type reference to
- constant of the container type. The modifier function makes
- a deep copy of its argument. For instance:
- </p>
-
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- ...
- &lt;/sequence>
- &lt;anyAttribute namespace="##other"/>
-&lt;/complexType>
- </pre>
-
- <p>is mapped to:</p>
-
- <pre class="c++">
-class object: public xml_schema::type
-{
-public:
- // Type definitions.
- //
- typedef attribute_set any_attribute_set;
- typedef any_attribute_set::iterator any_attribute_iterator;
- typedef any_attribute_set::const_iterator any_attribute_const_iterator;
-
- // Accessors.
- //
- const any_attribute_set&amp;
- any_attribute () const;
-
- any_attribute_set&amp;
- any_attribute ();
-
- // Modifier.
- //
- void
- any_attribute (const any_attribute_set&amp;);
-
- ...
-
-};
- </pre>
-
- <p>The <code>attribute_set</code> class is an associative container
- similar to the <code>std::set</code> class template as defined by
- the ISO/ANSI Standard for C++ (ISO/IEC 14882:1998, Section 23.3.3,
- "Class template set") with the key being the attribute's name
- and namespace. Unlike <code>std::set</code>, <code>attribute_set</code>
- allows searching using names and namespaces instead of
- <code>xercesc::DOMAttr</code> objects. It is defined in an
- implementation-specific namespace and its interface is presented
- below:
- </p>
-
- <pre class="c++">
-class attribute_set
-{
-public:
- typedef xercesc::DOMAttr key_type;
- typedef xercesc::DOMAttr value_type;
- typedef xercesc::DOMAttr* pointer;
- typedef const xercesc::DOMAttr* const_pointer;
- typedef xercesc::DOMAttr&amp; reference;
- typedef const xercesc::DOMAttr&amp; const_reference;
-
- typedef &lt;implementation-defined> iterator;
- typedef &lt;implementation-defined> const_iterator;
- typedef &lt;implementation-defined> reverse_iterator;
- typedef &lt;implementation-defined> const_reverse_iterator;
-
- typedef &lt;implementation-defined> size_type;
- typedef &lt;implementation-defined> difference_type;
- typedef &lt;implementation-defined> allocator_type;
-
-public:
- attribute_set (xercesc::DOMDocument&amp;);
-
- template &lt;typename I>
- attribute_set (const I&amp; begin, const I&amp; end, xercesc::DOMDocument&amp;);
-
- attribute_set (const attribute_set&amp;, xercesc::DOMDocument&amp;);
-
- attribute_set&amp;
- operator= (const attribute_set&amp;);
-
-public:
- const_iterator
- begin () const;
-
- const_iterator
- end () const;
-
- iterator
- begin ();
-
- iterator
- end ();
-
- const_reverse_iterator
- rbegin () const;
-
- const_reverse_iterator
- rend () const;
-
- reverse_iterator
- rbegin ();
-
- reverse_iterator
- rend ();
-
-public:
- size_type
- size () const;
-
- size_type
- max_size () const;
-
- bool
- empty () const;
-
- void
- clear ();
-
-public:
- // Makes a deep copy.
- //
- std::pair&lt;iterator, bool>
- insert (const xercesc::DOMAttr&amp;);
-
- // Assumes ownership.
- //
- std::pair&lt;iterator, bool>
- insert (xercesc::DOMAttr*);
-
- // Makes a deep copy.
- //
- iterator
- insert (iterator position, const xercesc::DOMAttr&amp;);
-
- // Assumes ownership.
- //
- iterator
- insert (iterator position, xercesc::DOMAttr*);
-
- template &lt;typename I>
- void
- insert (const I&amp; begin, const I&amp; end);
-
-public:
- void
- erase (iterator position);
-
- size_type
- erase (const std::basic_string&lt;C>&amp; name);
-
- size_type
- erase (const std::basic_string&lt;C>&amp; namespace_,
- const std::basic_string&lt;C>&amp; name);
-
- size_type
- erase (const XMLCh* name);
-
- size_type
- erase (const XMLCh* namespace_, const XMLCh* name);
-
- void
- erase (iterator begin, iterator end);
-
-public:
- size_type
- count (const std::basic_string&lt;C>&amp; name) const;
-
- size_type
- count (const std::basic_string&lt;C>&amp; namespace_,
- const std::basic_string&lt;C>&amp; name) const;
-
- size_type
- count (const XMLCh* name) const;
-
- size_type
- count (const XMLCh* namespace_, const XMLCh* name) const;
-
- iterator
- find (const std::basic_string&lt;C>&amp; name);
-
- iterator
- find (const std::basic_string&lt;C>&amp; namespace_,
- const std::basic_string&lt;C>&amp; name);
-
- iterator
- find (const XMLCh* name);
-
- iterator
- find (const XMLCh* namespace_, const XMLCh* name);
-
- const_iterator
- find (const std::basic_string&lt;C>&amp; name) const;
-
- const_iterator
- find (const std::basic_string&lt;C>&amp; namespace_,
- const std::basic_string&lt;C>&amp; name) const;
-
- const_iterator
- find (const XMLCh* name) const;
-
- const_iterator
- find (const XMLCh* namespace_, const XMLCh* name) const;
-
-public:
- // Note that the DOMDocument object of the two sets being
- // swapped should be the same.
- //
- void
- swap (attribute_set&amp;);
-};
-
-bool
-operator== (const attribute_set&amp;, const attribute_set&amp;);
-
-bool
-operator!= (const attribute_set&amp;, const attribute_set&amp;);
- </pre>
-
- <p>The following code shows how one could use this mapping:</p>
-
- <pre class="c++">
-void
-f (object&amp; o, const xercesc::DOMAttr&amp; a)
-{
- using namespace xercesc;
-
- object::any_attribute_set&amp; s (o.any_attribute ());
-
- // Iteration.
- //
- for (object::any_attribute_iterator i (s.begin ()); i != s.end (); ++i)
- {
- DOMAttr&amp; a (*i);
- }
-
- // Modification.
- //
- s.insert (a); // deep copy
- DOMDocument&amp; doc (o.dom_document ());
- s.insert (doc.createAttribute (...)); // assumes ownership
-
- // Searching.
- //
- object::any_attribute_iterator i (s.find ("name"));
- i = s.find ("http://www.w3.org/XML/1998/namespace", "lang");
-}
- </pre>
-
- <!-- Mapping for Mixed Content Models -->
-
- <h2><a name="2.13">2.13 Mapping for Mixed Content Models</a></h2>
-
- <p>For XML Schema types with mixed content models C++/Tree provides
- mapping support only if the type is marked as ordered
- (<a href="#2.8.4">Section 2.8.4, "Element Order"</a>). Use the
- <code>--ordered-type-mixed</code> XSD compiler option to
- automatically mark all types with mixed content as ordered.</p>
-
- <p>For an ordered type with mixed content, C++/Tree adds an extra
- text content sequence that is used to store the text fragments.
- This text content sequence is also assigned the content id and
- its entries are included in the content order sequence, just
- like elements. As a result, it is possible to capture the order
- between elements and text fragments.</p>
-
- <p>As an example, consider the following schema that describes text
- with embedded links:</p>
-
- <pre class="xml">
-&lt;complexType name="anchor">
- &lt;simpleContent>
- &lt;extension base="string">
- &lt;attribute name="href" type="anyURI" use="required"/>
- &lt;/extension>
- &lt;/simpleContent>
-&lt;/complexType>
-
-&lt;complexType name="text" mixed="true">
- &lt;sequence>
- &lt;element name="a" type="anchor" minOccurs="0" maxOccurs="unbounded"/>
- &lt;/sequence>
-&lt;/complexType>
- </pre>
-
- <p>The generated <code>text</code> C++ class will provide the following
- API (assuming it is marked as ordered):</p>
-
- <pre class="c++">
-class text: public xml_schema::type
-{
-public:
- // a
- //
- typedef anchor a_type;
- typedef sequence&lt;a_type> a_sequence;
- typedef a_sequence::iterator a_iterator;
- typedef a_sequence::const_iterator a_const_iterator;
-
- static const std::size_t a_id = 1UL;
-
- const a_sequence&amp;
- a () const;
-
- a_sequence&amp;
- a ();
-
- void
- a (const a_sequence&amp;);
-
- // text_content
- //
- typedef xml_schema::string text_content_type;
- typedef sequence&lt;text_content_type> text_content_sequence;
- typedef text_content_sequence::iterator text_content_iterator;
- typedef text_content_sequence::const_iterator text_content_const_iterator;
-
- static const std::size_t text_content_id = 2UL;
-
- const text_content_sequence&amp;
- text_content () const;
-
- text_content_sequence&amp;
- text_content ();
-
- void
- text_content (const text_content_sequence&amp;);
-
- // content_order
- //
- typedef xml_schema::content_order content_order_type;
- typedef std::vector&lt;content_order_type> content_order_sequence;
- typedef content_order_sequence::iterator content_order_iterator;
- typedef content_order_sequence::const_iterator content_order_const_iterator;
-
- const content_order_sequence&amp;
- content_order () const;
-
- content_order_sequence&amp;
- content_order ();
-
- void
- content_order (const content_order_sequence&amp;);
-
- ...
-};
- </pre>
-
- <p>Given this interface we can iterate over both link elements
- and text in content order. The following code fragment converts
- our format to plain text with references.</p>
-
- <pre class="c++">
-const text&amp; t = ...
-
-for (text::content_order_const_iterator i (t.content_order ().begin ());
- i != t.content_order ().end ();
- ++i)
-{
- switch (i->id)
- {
- case text::a_id:
- {
- const anchor&amp; a (t.a ()[i->index]);
- cerr &lt;&lt; a &lt;&lt; "[" &lt;&lt; a.href () &lt;&lt; "]";
- break;
- }
- case text::text_content_id:
- {
- const xml_schema::string&amp; s (t.text_content ()[i->index]);
- cerr &lt;&lt; s;
- break;
- }
- default:
- {
- assert (false); // Unknown content id.
- }
- }
-}
- </pre>
-
- <p>For the complete working code that shows the use of mixed content
- in ordered types refer to the <code>order/mixed</code> example in
- the <code>examples/cxx/tree/</code> directory in the XSD
- distribution.</p>
-
- <!-- Parsing -->
-
-
- <h1><a name="3">3 Parsing</a></h1>
-
- <p>This chapter covers various aspects of parsing XML instance
- documents in order to obtain corresponding tree-like object
- model.
- </p>
-
- <p>Each global XML Schema element in the form:</p>
-
- <pre class="xml">
-&lt;element name="name" type="type"/>
- </pre>
-
- <p>is mapped to 14 overloaded C++ functions in the form:</p>
-
- <pre class="c++">
-// Read from a URI or a local file.
-//
-
-std::[auto|unique]_ptr&lt;type>
-name (const std::basic_string&lt;C>&amp; uri,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (const std::basic_string&lt;C>&amp; uri,
- xml_schema::error_handler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (const std::basic_string&lt;C>&amp; uri,
- xercesc::DOMErrorHandler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-
-// Read from std::istream.
-//
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- xml_schema::error_handler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- xercesc::DOMErrorHandler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- const std::basic_string&lt;C>&amp; id,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- const std::basic_string&lt;C>&amp; id,
- xml_schema::error_handler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (std::istream&amp;,
- const std::basic_string&lt;C>&amp; id,
- xercesc::DOMErrorHandler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-
-// Read from InputSource.
-//
-
-std::[auto|unique]_ptr&lt;type>
-name (xercesc::InputSource&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (xercesc::InputSource&amp;,
- xml_schema::error_handler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (xercesc::InputSource&amp;,
- xercesc::DOMErrorHandler&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-
-// Read from DOM.
-//
-
-std::[auto|unique]_ptr&lt;type>
-name (const xercesc::DOMDocument&amp;,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
-
-std::[auto|unique]_ptr&lt;type>
-name (xml_schema::dom::[auto|unique]_ptr&lt;xercesc::DOMDocument>,
- xml_schema::flags = 0,
- const xml_schema::properties&amp; = xml_schema::properties ());
- </pre>
-
- <p>You can choose between reading an XML instance from a local file,
- URI, <code>std::istream</code>, <code>xercesc::InputSource</code>,
- or a pre-parsed DOM instance in the form of
- <code>xercesc::DOMDocument</code>. All the parsing functions
- return a dynamically allocated object model as either
- <code>std::auto_ptr</code> or <code>std::unique_ptr</code>,
- depending on the C++ standard selected. Each of these parsing
- functions is discussed in more detail in the following sections.
- </p>
-
- <h2><a name="3.1">3.1 Initializing the Xerces-C++ Runtime</a></h2>
-
- <p>Some parsing functions expect you to initialize the Xerces-C++
- runtime while others initialize and terminate it as part of their
- work. The general rule is as follows: if a function has any arguments
- or return a value that is an instance of a Xerces-C++ type, then
- this function expects you to initialize the Xerces-C++ runtime.
- Otherwise, the function initializes and terminates the runtime for
- you. Note that it is legal to have nested calls to the Xerces-C++
- initialize and terminate functions as long as the calls are balanced.
- </p>
-
- <p>You can instruct parsing functions that initialize and terminate
- the runtime not to do so by passing the
- <code>xml_schema::flags::dont_initialize</code> flag (see
- <a href="#3.2">Section 3.2, "Flags and Properties"</a>).
- </p>
-
-
- <h2><a name="3.2">3.2 Flags and Properties</a></h2>
-
- <p>Parsing flags and properties are the last two arguments of every
- parsing function. They allow you to fine-tune the process of
- instance validation and parsing. Both arguments are optional.
- </p>
-
-
- <p>The following flags are recognized by the parsing functions:</p>
-
- <dl>
- <dt><code>xml_schema::flags::keep_dom</code></dt>
- <dd>Keep association between DOM nodes and the resulting
- object model nodes. For more information about DOM association
- refer to <a href="#5.1">Section 5.1, "DOM Association"</a>.</dd>
-
- <dt><code>xml_schema::flags::own_dom</code></dt>
- <dd>Assume ownership of the DOM document passed. This flag only
- makes sense together with the <code>keep_dom</code> flag in
- the call to the parsing function with the
- <code>xml_schema::dom::[auto|unique]_ptr&lt;DOMDocument></code>
- argument.</dd>
-
- <dt><code>xml_schema::flags::dont_validate</code></dt>
- <dd>Do not validate instance documents against schemas.</dd>
-
- <dt><code>xml_schema::flags::dont_initialize</code></dt>
- <dd>Do not initialize the Xerces-C++ runtime.</dd>
- </dl>
-
- <p>You can pass several flags by combining them using the bit-wise OR
- operator. For example:</p>
-
- <pre class="c++">
-using xml_schema::flags;
-
-std::auto_ptr&lt;type> r (
- name ("test.xml", flags::keep_dom | flags::dont_validate));
- </pre>
-
- <p>By default, validation of instance documents is turned on even
- though parsers generated by XSD do not assume instance
- documents are valid. They include a number of checks that prevent
- construction of inconsistent object models. This,
- however, does not mean that an instance document that was
- successfully parsed by the XSD-generated parsers is
- valid per the corresponding schema. If an instance document is not
- "valid enough" for the generated parsers to construct consistent
- object model, one of the exceptions defined in
- <code>xml_schema</code> namespace is thrown (see
- <a href="#3.3">Section 3.3, "Error Handling"</a>).
- </p>
-
- <p>For more information on the Xerces-C++ runtime initialization
- refer to <a href="#3.1">Section 3.1, "Initializing the Xerces-C++
- Runtime"</a>.
- </p>
-
- <p>The <code>xml_schema::properties</code> class allows you to
- programmatically specify schema locations to be used instead
- of those specified with the <code>xsi::schemaLocation</code>
- and <code>xsi::noNamespaceSchemaLocation</code> attributes
- in instance documents. The interface of the <code>properties</code>
- class is presented below:
- </p>
-
- <pre class="c++">
-class properties
-{
-public:
- void
- schema_location (const std::basic_string&lt;C>&amp; namespace_,
- const std::basic_string&lt;C>&amp; location);
- void
- no_namespace_schema_location (const std::basic_string&lt;C>&amp; location);
-};
- </pre>
-
- <p>Note that all locations are relative to an instance document unless
- they are URIs. For example, if you want to use a local file as your
- schema, then you will need to pass
- <code>file:///absolute/path/to/your/schema</code> as the location
- argument.
- </p>
-
- <h2><a name="3.3">3.3 Error Handling</a></h2>
-
- <p>As discussed in <a href="#2.2">Section 2.2, "Error Handling"</a>,
- the mapping uses the C++ exception handling mechanism as its primary
- way of reporting error conditions. However, to handle recoverable
- parsing and validation errors and warnings, a callback interface maybe
- preferred by the application.</p>
-
- <p>To better understand error handling and reporting strategies employed
- by the parsing functions, it is useful to know that the
- transformation of an XML instance document to a statically-typed
- tree happens in two stages. The first stage, performed by Xerces-C++,
- consists of parsing an XML document into a DOM instance. For short,
- we will call this stage the XML-DOM stage. Validation, if not disabled,
- happens during this stage. The second stage,
- performed by the generated parsers, consist of parsing the DOM
- instance into the statically-typed tree. We will call this stage
- the DOM-Tree stage. Additional checks are performed during this
- stage in order to prevent construction of inconsistent tree which
- could otherwise happen when validation is disabled, for example.</p>
-
- <p>All parsing functions except the one that operates on a DOM instance
- come in overloaded triples. The first function in such a triple
- reports error conditions exclusively by throwing exceptions. It
- accumulates all the parsing and validation errors of the XML-DOM
- stage and throws them in a single instance of the
- <code>xml_schema::parsing</code> exception (described below).
- The second and the third functions in the triple use callback
- interfaces to report parsing and validation errors and warnings.
- The two callback interfaces are <code>xml_schema::error_handler</code>
- and <code>xercesc::DOMErrorHandler</code>. For more information
- on the <code>xercesc::DOMErrorHandler</code> interface refer to
- the Xerces-C++ documentation. The <code>xml_schema::error_handler</code>
- interface is presented below:
- </p>
-
- <pre class="c++">
-class error_handler
-{
-public:
- struct severity
- {
- enum value
- {
- warning,
- error,
- fatal
- };
- };
-
- virtual bool
- handle (const std::basic_string&lt;C>&amp; id,
- unsigned long line,
- unsigned long column,
- severity,
- const std::basic_string&lt;C>&amp; message) = 0;
-
- virtual
- ~error_handler ();
-};
- </pre>
-
- <p>The <code>id</code> argument of the <code>error_handler::handle</code>
- function identifies the resource being parsed (e.g., a file name or
- URI).
- </p>
-
- <p>By returning <code>true</code> from the <code>handle</code> function
- you instruct the parser to recover and continue parsing. Returning
- <code>false</code> results in termination of the parsing process.
- An error with the <code>fatal</code> severity level results in
- termination of the parsing process no matter what is returned from
- the <code>handle</code> function. It is safe to throw an exception
- from the <code>handle</code> function.
- </p>
-
- <p>The DOM-Tree stage reports error conditions exclusively by throwing
- exceptions. Individual exceptions thrown by the parsing functions
- are described in the following sub-sections.
- </p>
-
-
- <h3><a name="3.3.1">3.3.1 <code>xml_schema::parsing</code></a></h3>
-
- <pre class="c++">
-struct severity
-{
- enum value
- {
- warning,
- error
- };
-
- severity (value);
- operator value () const;
-};
-
-struct error
-{
- error (severity,
- const std::basic_string&lt;C>&amp; id,
- unsigned long line,
- unsigned long column,
- const std::basic_string&lt;C>&amp; message);
-
- severity
- severity () const;
-
- const std::basic_string&lt;C>&amp;
- id () const;
-
- unsigned long
- line () const;
-
- unsigned long
- column () const;
-
- const std::basic_string&lt;C>&amp;
- message () const;
-};
-
-std::basic_ostream&lt;C>&amp;
-operator&lt;&lt; (std::basic_ostream&lt;C>&amp;, const error&amp;);
-
-struct diagnostics: std::vector&lt;error>
-{
-};
-
-std::basic_ostream&lt;C>&amp;
-operator&lt;&lt; (std::basic_ostream&lt;C>&amp;, const diagnostics&amp;);
-
-struct parsing: virtual exception
-{
- parsing ();
- parsing (const diagnostics&amp;);
-
- const diagnostics&amp;
- diagnostics () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::parsing</code> exception is thrown if there
- were parsing or validation errors reported during the XML-DOM stage.
- If no callback interface was provided to the parsing function, the
- exception contains a list of errors and warnings accessible using
- the <code>diagnostics</code> function. The usual conditions when
- this exception is thrown include malformed XML instances and, if
- validation is turned on, invalid instance documents.
- </p>
-
- <h3><a name="3.3.2">3.3.2 <code>xml_schema::expected_element</code></a></h3>
-
- <pre class="c++">
-struct expected_element: virtual exception
-{
- expected_element (const std::basic_string&lt;C>&amp; name,
- const std::basic_string&lt;C>&amp; namespace_);
-
-
- const std::basic_string&lt;C>&amp;
- name () const;
-
- const std::basic_string&lt;C>&amp;
- namespace_ () const;
-
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::expected_element</code> exception is thrown
- when an expected element is not encountered by the DOM-Tree stage.
- The name and namespace of the expected element can be obtained using
- the <code>name</code> and <code>namespace_</code> functions respectively.
- </p>
-
-
- <h3><a name="3.3.3">3.3.3 <code>xml_schema::unexpected_element</code></a></h3>
-
- <pre class="c++">
-struct unexpected_element: virtual exception
-{
- unexpected_element (const std::basic_string&lt;C>&amp; encountered_name,
- const std::basic_string&lt;C>&amp; encountered_namespace,
- const std::basic_string&lt;C>&amp; expected_name,
- const std::basic_string&lt;C>&amp; expected_namespace)
-
-
- const std::basic_string&lt;C>&amp;
- encountered_name () const;
-
- const std::basic_string&lt;C>&amp;
- encountered_namespace () const;
-
-
- const std::basic_string&lt;C>&amp;
- expected_name () const;
-
- const std::basic_string&lt;C>&amp;
- expected_namespace () const;
-
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::unexpected_element</code> exception is thrown
- when an unexpected element is encountered by the DOM-Tree stage.
- The name and namespace of the encountered element can be obtained
- using the <code>encountered_name</code> and
- <code>encountered_namespace</code> functions respectively. If an
- element was expected instead of the encountered one, its name
- and namespace can be obtained using the <code>expected_name</code> and
- <code>expected_namespace</code> functions respectively. Otherwise
- these functions return empty strings.
- </p>
-
- <h3><a name="3.3.4">3.3.4 <code>xml_schema::expected_attribute</code></a></h3>
-
- <pre class="c++">
-struct expected_attribute: virtual exception
-{
- expected_attribute (const std::basic_string&lt;C>&amp; name,
- const std::basic_string&lt;C>&amp; namespace_);
-
-
- const std::basic_string&lt;C>&amp;
- name () const;
-
- const std::basic_string&lt;C>&amp;
- namespace_ () const;
-
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::expected_attribute</code> exception is thrown
- when an expected attribute is not encountered by the DOM-Tree stage.
- The name and namespace of the expected attribute can be obtained using
- the <code>name</code> and <code>namespace_</code> functions respectively.
- </p>
-
-
- <h3><a name="3.3.5">3.3.5 <code>xml_schema::unexpected_enumerator</code></a></h3>
-
- <pre class="c++">
-struct unexpected_enumerator: virtual exception
-{
- unexpected_enumerator (const std::basic_string&lt;C>&amp; enumerator);
-
- const std::basic_string&lt;C>&amp;
- enumerator () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::unexpected_enumerator</code> exception is thrown
- when an unexpected enumerator is encountered by the DOM-Tree stage.
- The enumerator can be obtained using the <code>enumerator</code>
- functions.
- </p>
-
- <h3><a name="3.3.6">3.3.6 <code>xml_schema::expected_text_content</code></a></h3>
-
- <pre class="c++">
-struct expected_text_content: virtual exception
-{
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::expected_text_content</code> exception is thrown
- when a content other than text is encountered and the text content was
- expected by the DOM-Tree stage.
- </p>
-
- <h3><a name="3.3.7">3.3.7 <code>xml_schema::no_type_info</code></a></h3>
-
- <pre class="c++">
-struct no_type_info: virtual exception
-{
- no_type_info (const std::basic_string&lt;C>&amp; type_name,
- const std::basic_string&lt;C>&amp; type_namespace);
-
- const std::basic_string&lt;C>&amp;
- type_name () const;
-
- const std::basic_string&lt;C>&amp;
- type_namespace () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::no_type_info</code> exception is thrown
- when there is no type information associated with a type specified
- by the <code>xsi:type</code> attribute. This exception is thrown
- by the DOM-Tree stage. The name and namespace of the type in question
- can be obtained using the <code>type_name</code> and
- <code>type_namespace</code> functions respectively. Usually, catching
- this exception means that you haven't linked the code generated
- from the schema defining the type in question with your application
- or this schema has been compiled without the
- <code>--generate-polymorphic</code> option.
- </p>
-
-
- <h3><a name="3.3.8">3.3.8 <code>xml_schema::not_derived</code></a></h3>
-
- <pre class="c++">
-struct not_derived: virtual exception
-{
- not_derived (const std::basic_string&lt;C>&amp; base_type_name,
- const std::basic_string&lt;C>&amp; base_type_namespace,
- const std::basic_string&lt;C>&amp; derived_type_name,
- const std::basic_string&lt;C>&amp; derived_type_namespace);
-
- const std::basic_string&lt;C>&amp;
- base_type_name () const;
-
- const std::basic_string&lt;C>&amp;
- base_type_namespace () const;
-
-
- const std::basic_string&lt;C>&amp;
- derived_type_name () const;
-
- const std::basic_string&lt;C>&amp;
- derived_type_namespace () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::not_derived</code> exception is thrown
- when a type specified by the <code>xsi:type</code> attribute is
- not derived from the expected base type. This exception is thrown
- by the DOM-Tree stage. The name and namespace of the expected
- base type can be obtained using the <code>base_type_name</code> and
- <code>base_type_namespace</code> functions respectively. The name
- and namespace of the offending type can be obtained using the
- <code>derived_type_name</code> and
- <code>derived_type_namespace</code> functions respectively.
- </p>
-
- <h3><a name="3.3.9">3.3.9 <code>xml_schema::no_prefix_mapping</code></a></h3>
-
- <pre class="c++">
-struct no_prefix_mapping: virtual exception
-{
- no_prefix_mapping (const std::basic_string&lt;C>&amp; prefix);
-
- const std::basic_string&lt;C>&amp;
- prefix () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::no_prefix_mapping</code> exception is thrown
- during the DOM-Tree stage if a namespace prefix is encountered for
- which a prefix-namespace mapping hasn't been provided. The namespace
- prefix in question can be obtained using the <code>prefix</code>
- function.
- </p>
-
- <h2><a name="3.4">3.4 Reading from a Local File or URI</a></h2>
-
- <p>Using a local file or URI is the simplest way to parse an XML instance.
- For example:</p>
-
- <pre class="c++">
-using std::auto_ptr;
-
-auto_ptr&lt;type> r1 (name ("test.xml"));
-auto_ptr&lt;type> r2 (name ("https://www.codesynthesis.com/test.xml"));
- </pre>
-
- <p>Or, in the C++11 mode:</p>
-
- <pre class="c++">
-using std::unique_ptr;
-
-unique_ptr&lt;type> r1 (name ("test.xml"));
-unique_ptr&lt;type> r2 (name ("https://www.codesynthesis.com/test.xml"));
- </pre>
-
- <h2><a name="3.5">3.5 Reading from <code>std::istream</code></a></h2>
-
- <p>When using an <code>std::istream</code> instance, you may also
- pass an optional resource id. This id is used to identify the
- resource (for example in error messages) as well as to resolve
- relative paths. For instance:</p>
-
- <pre class="c++">
-using std::auto_ptr;
-
-{
- std::ifstream ifs ("test.xml");
- auto_ptr&lt;type> r (name (ifs, "test.xml"));
-}
-
-{
- std::string str ("..."); // Some XML fragment.
- std::istringstream iss (str);
- auto_ptr&lt;type> r (name (iss));
-}
- </pre>
-
- <h2><a name="3.6">3.6 Reading from <code>xercesc::InputSource</code></a></h2>
-
- <p>Reading from a <code>xercesc::InputSource</code> instance
- is similar to the <code>std::istream</code> case except
- the resource id is maintained by the <code>InputSource</code>
- object. For instance:</p>
-
- <pre class="c++">
-xercesc::StdInInputSource is;
-std::auto_ptr&lt;type> r (name (is));
- </pre>
-
- <h2><a name="3.7">3.7 Reading from DOM</a></h2>
-
- <p>Reading from a <code>xercesc::DOMDocument</code> instance allows
- you to setup a custom XML-DOM stage. Things like DOM
- parser reuse, schema pre-parsing, and schema caching can be achieved
- with this approach. For more information on how to obtain DOM
- representation from an XML instance refer to the Xerces-C++
- documentation. In addition, the
- <a href="http://wiki.codesynthesis.com/Tree/FAQ">C++/Tree Mapping
- FAQ</a> shows how to parse an XML instance to a Xerces-C++
- DOM document using the XSD runtime utilities.
- </p>
-
- <p>The last parsing function is useful when you would like to perform
- your own XML-to-DOM parsing and associate the resulting DOM document
- with the object model nodes. The automatic <code>DOMDocument</code>
- pointer is reset and the resulting object model assumes ownership
- of the DOM document passed. For example:</p>
-
- <pre class="c++">
-// C++98 version.
-//
-xml_schema::dom::auto_ptr&lt;xercesc::DOMDocument> doc = ...
-
-std::auto_ptr&lt;type> r (
- name (doc, xml_schema::flags::keep_dom | xml_schema::flags::own_dom));
-
-// At this point doc is reset to 0.
-
-// C++11 version.
-//
-xml_schema::dom::unique_ptr&lt;xercesc::DOMDocument> doc = ...
-
-std::unique_ptr&lt;type> r (
- name (std::move (doc),
- xml_schema::flags::keep_dom | xml_schema::flags::own_dom));
-
-// At this point doc is reset to 0.
- </pre>
-
- <h1><a name="4">4 Serialization</a></h1>
-
- <p>This chapter covers various aspects of serializing a
- tree-like object model to DOM or XML.
- In this regard, serialization is complimentary to the reverse
- process of parsing a DOM or XML instance into an object model
- which is discussed in <a href="#3">Chapter 3,
- "Parsing"</a>. Note that the generation of the serialization code
- is optional and should be explicitly requested with the
- <code>--generate-serialization</code> option. See the
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a> for more information.
- </p>
-
- <p>Each global XML Schema element in the form:
- </p>
-
-
- <pre class="xml">
-&lt;xsd:element name="name" type="type"/>
- </pre>
-
- <p>is mapped to 8 overloaded C++ functions in the form:</p>
-
- <pre class="c++">
-// Serialize to std::ostream.
-//
-void
-name (std::ostream&amp;,
- const type&amp;,
- const xml_schema::namespace_fomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-void
-name (std::ostream&amp;,
- const type&amp;,
- xml_schema::error_handler&amp;,
- const xml_schema::namespace_infomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-void
-name (std::ostream&amp;,
- const type&amp;,
- xercesc::DOMErrorHandler&amp;,
- const xml_schema::namespace_infomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-
-// Serialize to XMLFormatTarget.
-//
-void
-name (xercesc::XMLFormatTarget&amp;,
- const type&amp;,
- const xml_schema::namespace_infomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-void
-name (xercesc::XMLFormatTarget&amp;,
- const type&amp;,
- xml_schema::error_handler&amp;,
- const xml_schema::namespace_infomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-void
-name (xercesc::XMLFormatTarget&amp;,
- const type&amp;,
- xercesc::DOMErrorHandler&amp;,
- const xml_schema::namespace_infomap&amp; =
- xml_schema::namespace_infomap (),
- const std::basic_string&lt;C>&amp; encoding = "UTF-8",
- xml_schema::flags = 0);
-
-
-// Serialize to DOM.
-//
-xml_schema::dom::[auto|unique]_ptr&lt;xercesc::DOMDocument>
-name (const type&amp;,
- const xml_schema::namespace_infomap&amp;
- xml_schema::namespace_infomap (),
- xml_schema::flags = 0);
-
-void
-name (xercesc::DOMDocument&amp;,
- const type&amp;,
- xml_schema::flags = 0);
- </pre>
-
- <p>You can choose between writing XML to <code>std::ostream</code> or
- <code>xercesc::XMLFormatTarget</code> and creating a DOM instance
- in the form of <code>xercesc::DOMDocument</code>. Serialization
- to <code>ostream</code> or <code>XMLFormatTarget</code> requires a
- considerably less work while serialization to DOM provides
- for greater flexibility. Each of these serialization functions
- is discussed in more detail in the following sections.
- </p>
-
-
- <h2><a name="4.1">4.1 Initializing the Xerces-C++ Runtime</a></h2>
-
- <p>Some serialization functions expect you to initialize the Xerces-C++
- runtime while others initialize and terminate it as part of their
- work. The general rule is as follows: if a function has any arguments
- or return a value that is an instance of a Xerces-C++ type, then
- this function expects you to initialize the Xerces-C++ runtime.
- Otherwise, the function initializes and terminates the runtime for
- you. Note that it is legal to have nested calls to the Xerces-C++
- initialize and terminate functions as long as the calls are balanced.
- </p>
-
- <p>You can instruct serialization functions that initialize and terminate
- the runtime not to do so by passing the
- <code>xml_schema::flags::dont_initialize</code> flag (see
- <a href="#4.3">Section 4.3, "Flags"</a>).
- </p>
-
- <h2><a name="4.2">4.2 Namespace Infomap and Character Encoding</a></h2>
-
- <p>When a document being serialized uses XML namespaces, custom
- prefix-namespace associations can to be established. If custom
- prefix-namespace mapping is not provided then generic prefixes
- (<code>p1</code>, <code>p2</code>, etc) are automatically assigned
- to namespaces as needed. Also, if
- you would like the resulting instance document to contain the
- <code>schemaLocation</code> or <code>noNamespaceSchemaLocation</code>
- attributes, you will need to provide namespace-schema associations.
- The <code>xml_schema::namespace_infomap</code> class is used
- to capture this information:</p>
-
- <pre class="c++">
-struct namespace_info
-{
- namespace_info ();
- namespace_info (const std::basic_string&lt;C>&amp; name,
- const std::basic_string&lt;C>&amp; schema);
-
- std::basic_string&lt;C> name;
- std::basic_string&lt;C> schema;
-};
-
-// Map of namespace prefix to namespace_info.
-//
-struct namespace_infomap: public std::map&lt;std::basic_string&lt;C>,
- namespace_info>
-{
-};
- </pre>
-
- <p>Consider the following associations as an example:</p>
-
- <pre class="c++">
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
- </pre>
-
- <p>This map, if passed to one of the serialization functions,
- could result in the following XML fragment:</p>
-
- <pre class="xml">
-&lt;?xml version="1.0" ?>
-&lt;t:name xmlns:t="https://www.codesynthesis.com/test"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="https://www.codesynthesis.com/test test.xsd">
- </pre>
-
- <p>As you can see, the serialization function automatically added namespace
- mapping for the <code>xsi</code> prefix. You can change this by
- providing your own prefix:</p>
-
- <pre class="c++">
-xml_schema::namespace_infomap map;
-
-map["xsn"].name = "http://www.w3.org/2001/XMLSchema-instance";
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
- </pre>
-
- <p>This could result in the following XML fragment:</p>
-
- <pre class="xml">
-&lt;?xml version="1.0" ?>
-&lt;t:name xmlns:t="https://www.codesynthesis.com/test"
- xmlns:xsn="http://www.w3.org/2001/XMLSchema-instance"
- xsn:schemaLocation="https://www.codesynthesis.com/test test.xsd">
- </pre>
-
- <p>To specify the location of a schema without a namespace you can use
- an empty prefix as in the example below: </p>
-
- <pre class="c++">
-xml_schema::namespace_infomap map;
-
-map[""].schema = "test.xsd";
- </pre>
-
- <p>This would result in the following XML fragment:</p>
-
- <pre class="xml">
-&lt;?xml version="1.0" ?>
-&lt;name xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="test.xsd">
- </pre>
-
- <p>To make a particular namespace default you can use an empty
- prefix, for example:</p>
-
- <pre class="c++">
-xml_schema::namespace_infomap map;
-
-map[""].name = "https://www.codesynthesis.com/test";
-map[""].schema = "test.xsd";
- </pre>
-
- <p>This could result in the following XML fragment:</p>
-
- <pre class="xml">
-&lt;?xml version="1.0" ?>
-&lt;name xmlns="https://www.codesynthesis.com/test"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="https://www.codesynthesis.com/test test.xsd">
- </pre>
-
-
- <p>Another bit of information that you can pass to the serialization
- functions is the character encoding method that you would like to use.
- Common values for this argument are <code>"US-ASCII"</code>,
- <code>"ISO8859-1"</code>, <code>"UTF-8"</code>,
- <code>"UTF-16BE"</code>, <code>"UTF-16LE"</code>,
- <code>"UCS-4BE"</code>, and <code>"UCS-4LE"</code>. The default
- encoding is <code>"UTF-8"</code>. For more information on
- encoding methods see the
- "<a href="http://en.wikipedia.org/wiki/Character_code">Character
- Encoding</a>" article from Wikipedia.
- </p>
-
- <h2><a name="4.3">4.3 Flags</a></h2>
-
- <p>Serialization flags are the last argument of every serialization
- function. They allow you to fine-tune the process of serialization.
- The flags argument is optional.
- </p>
-
-
- <p>The following flags are recognized by the serialization
- functions:</p>
-
- <dl>
- <dt><code>xml_schema::flags::dont_initialize</code></dt>
- <dd>Do not initialize the Xerces-C++ runtime.</dd>
-
- <dt><code>xml_schema::flags::dont_pretty_print</code></dt>
- <dd>Do not add extra spaces or new lines that make the resulting XML
- slightly bigger but easier to read.</dd>
-
- <dt><code>xml_schema::flags::no_xml_declaration</code></dt>
- <dd>Do not write XML declaration (&lt;?xml ... ?>).</dd>
- </dl>
-
- <p>You can pass several flags by combining them using the bit-wise OR
- operator. For example:</p>
-
- <pre class="c++">
-std::auto_ptr&lt;type> r = ...
-std::ofstream ofs ("test.xml");
-xml_schema::namespace_infomap map;
-name (ofs,
- *r,
- map,
- "UTF-8",
- xml_schema::flags::no_xml_declaration |
- xml_schema::flags::dont_pretty_print);
- </pre>
-
- <p>For more information on the Xerces-C++ runtime initialization
- refer to <a href="#4.1">Section 4.1, "Initializing the Xerces-C++
- Runtime"</a>.
- </p>
-
- <h2><a name="4.4">4.4 Error Handling</a></h2>
-
- <p>As with the parsing functions (see <a href="#3.3">Section 3.3,
- "Error Handling"</a>), to better understand error handling and
- reporting strategies employed by the serialization functions, it
- is useful to know that the transformation of a statically-typed
- tree to an XML instance document happens in two stages. The first
- stage, performed by the generated code, consist of building a DOM
- instance from the statically-typed tree . For short, we will call
- this stage the Tree-DOM stage. The second stage, performed by
- Xerces-C++, consists of serializing the DOM instance into the XML
- document. We will call this stage the DOM-XML stage.
- </p>
-
- <p>All serialization functions except the two that serialize into
- a DOM instance come in overloaded triples. The first function
- in such a triple reports error conditions exclusively by throwing
- exceptions. It accumulates all the serialization errors of the
- DOM-XML stage and throws them in a single instance of the
- <code>xml_schema::serialization</code> exception (described below).
- The second and the third functions in the triple use callback
- interfaces to report serialization errors and warnings. The two
- callback interfaces are <code>xml_schema::error_handler</code> and
- <code>xercesc::DOMErrorHandler</code>. The
- <code>xml_schema::error_handler</code> interface is described in
- <a href="#3.3">Section 3.3, "Error Handling"</a>. For more information
- on the <code>xercesc::DOMErrorHandler</code> interface refer to the
- Xerces-C++ documentation.
- </p>
-
- <p>The Tree-DOM stage reports error conditions exclusively by throwing
- exceptions. Individual exceptions thrown by the serialization functions
- are described in the following sub-sections.
- </p>
-
- <h3><a name="4.4.1">4.4.1 <code>xml_schema::serialization</code></a></h3>
-
- <pre class="c++">
-struct serialization: virtual exception
-{
- serialization ();
- serialization (const diagnostics&amp;);
-
- const diagnostics&amp;
- diagnostics () const;
-
- virtual const char*
- what () const throw ();
-};
- </pre>
-
- <p>The <code>xml_schema::diagnostics</code> class is described in
- <a href="#3.3.1">Section 3.3.1, "<code>xml_schema::parsing</code>"</a>.
- The <code>xml_schema::serialization</code> exception is thrown if
- there were serialization errors reported during the DOM-XML stage.
- If no callback interface was provided to the serialization function,
- the exception contains a list of errors and warnings accessible using
- the <code>diagnostics</code> function.
- </p>
-
-
- <h3><a name="4.4.2">4.4.2 <code>xml_schema::unexpected_element</code></a></h3>
-
- <p>The <code>xml_schema::unexpected_element</code> exception is
- described in <a href="#3.3.3">Section 3.3.3,
- "<code>xml_schema::unexpected_element</code>"</a>. It is thrown
- by the serialization functions during the Tree-DOM stage if the
- root element name of the provided DOM instance does not match with
- the name of the element this serialization function is for.
- </p>
-
- <h3><a name="4.4.3">4.4.3 <code>xml_schema::no_type_info</code></a></h3>
-
- <p>The <code>xml_schema::no_type_info</code> exception is
- described in <a href="#3.3.7">Section 3.3.7,
- "<code>xml_schema::no_type_info</code>"</a>. It is thrown
- by the serialization functions during the Tree-DOM stage when there
- is no type information associated with a dynamic type of an
- element. Usually, catching this exception means that you haven't
- linked the code generated from the schema defining the type in
- question with your application or this schema has been compiled
- without the <code>--generate-polymorphic</code> option.
- </p>
-
- <h2><a name="4.5">4.5 Serializing to <code>std::ostream</code></a></h2>
-
- <p>In order to serialize to <code>std::ostream</code> you will need
- an object model, an output stream and, optionally, a namespace
- infomap. For instance:</p>
-
- <pre class="c++">
-// Obtain the object model.
-//
-std::auto_ptr&lt;type> r = ...
-
-// Prepare namespace mapping and schema location information.
-//
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-
-// Write it out.
-//
-name (std::cout, *r, map);
- </pre>
-
- <p>Note that the output stream is treated as a binary stream. This
- becomes important when you use a character encoding that is wider
- than 8-bit <code>char</code>, for instance UTF-16 or UCS-4. For
- example, things will most likely break if you try to serialize
- to <code>std::ostringstream</code> with UTF-16 or UCS-4 as an
- encoding. This is due to the special value,
- <code>'\0'</code>, that will most likely occur as part of such
- serialization and it won't have the special meaning assumed by
- <code>std::ostringstream</code>.
- </p>
-
-
- <h2><a name="4.6">4.6 Serializing to <code>xercesc::XMLFormatTarget</code></a></h2>
-
- <p>Serializing to an <code>xercesc::XMLFormatTarget</code> instance
- is similar the <code>std::ostream</code> case. For instance:
- </p>
-
- <pre class="c++">
-using std::auto_ptr;
-
-// Obtain the object model.
-//
-auto_ptr&lt;type> r = ...
-
-// Prepare namespace mapping and schema location information.
-//
-xml_schema::namespace_infomap map;
-
-map["t"].name = "https://www.codesynthesis.com/test";
-map["t"].schema = "test.xsd";
-
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
- // Choose a target.
- //
- auto_ptr&lt;XMLFormatTarget> ft;
-
- if (argc != 2)
- {
- ft = auto_ptr&lt;XMLFormatTarget> (new StdOutFormatTarget ());
- }
- else
- {
- ft = auto_ptr&lt;XMLFormatTarget> (
- new LocalFileFormatTarget (argv[1]));
- }
-
- // Write it out.
- //
- name (*ft, *r, map);
-}
-
-XMLPlatformUtils::Terminate ();
- </pre>
-
- <p>Note that we had to initialize the Xerces-C++ runtime before we
- could call this serialization function.</p>
-
- <h2><a name="4.7">4.7 Serializing to DOM</a></h2>
-
- <p>The mapping provides two overloaded functions that implement
- serialization to a DOM instance. The first creates a DOM instance
- for you and the second serializes to an existing DOM instance.
- While serializing to a new DOM instance is similar to serializing
- to <code>std::ostream</code> or <code>xercesc::XMLFormatTarget</code>,
- serializing to an existing DOM instance requires quite a bit of work
- from your side. You will need to set all the custom namespace mapping
- attributes as well as the <code>schemaLocation</code> and/or
- <code>noNamespaceSchemaLocation</code> attributes. The following
- listing should give you an idea about what needs to be done:
- </p>
-
- <pre class="c++">
-// Obtain the object model.
-//
-std::auto_ptr&lt;type> r = ...
-
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
- // Create a DOM instance. Set custom namespace mapping and schema
- // location attributes.
- //
- DOMDocument&amp; doc = ...
-
- // Serialize to DOM.
- //
- name (doc, *r);
-
- // Serialize the DOM document to XML.
- //
- ...
-}
-
-XMLPlatformUtils::Terminate ();
- </pre>
-
- <p>For more information on how to create and serialize a DOM instance
- refer to the Xerces-C++ documentation. In addition, the
- <a href="http://wiki.codesynthesis.com/Tree/FAQ">C++/Tree Mapping
- FAQ</a> shows how to implement these operations using the XSD
- runtime utilities.
- </p>
-
- <h1><a name="5">5 Additional Functionality</a></h1>
-
- <p>The C++/Tree mapping provides a number of optional features
- that can be useful in certain situations. They are described
- in the following sections.</p>
-
- <h2><a name="5.1">5.1 DOM Association</a></h2>
-
- <p>Normally, after parsing is complete, the DOM document which
- was used to extract the data is discarded. However, the parsing
- functions can be instructed to preserve the DOM document
- and create an association between the DOM nodes and object model
- nodes. When there is an association between the DOM and
- object model nodes, you can obtain the corresponding DOM element
- or attribute node from an object model node as well as perform
- the reverse transition: obtain the corresponding object model
- from a DOM element or attribute node.</p>
-
- <p>Maintaining DOM association is normally useful when the application
- needs access to XML constructs that are not preserved in the
- object model, for example, XML comments.
- Another useful aspect of DOM association is the ability of the
- application to navigate the document tree using the generic DOM
- interface (for example, with the help of an XPath processor)
- and then move back to the statically-typed object model. Note
- also that while you can change the underlying DOM document,
- these changes are not reflected in the object model and will
- be ignored during serialization. If you need to not only access
- but also modify some aspects of XML that are not preserved in
- the object model, then type customization with custom parsing
- constructors and serialization operators should be used instead.</p>
-
- <p>To request DOM association you will need to pass the
- <code>xml_schema::flags::keep_dom</code> flag to one of the
- parsing functions (see <a href="#3.2">Section 3.2,
- "Flags and Properties"</a> for more information). In this case the
- DOM document is retained and will be released when the object model
- is deleted. Note that since DOM nodes "out-live" the parsing function
- call, you need to initialize the Xerces-C++ runtime before calling
- one of the parsing functions with the <code>keep_dom</code> flag and
- terminate it after the object model is destroyed (see
- <a href="#3.1">Section 3.1, "Initializing the Xerces-C++ Runtime"</a>).</p>
-
- <p>If the <code>keep_dom</code> flag is passed
- as the second argument to the copy constructor and the copy
- being made is of a complete tree, then the DOM association
- is also maintained in the copy by cloning the underlying
- DOM document and reestablishing the associations. For example:</p>
-
- <pre class="c++">
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
- // Parse XML to object model.
- //
- std::auto_ptr&lt;type> r (root (
- "root.xml",
- xml_schema::flags::keep_dom |
- xml_schema::flags::dont_initialize));
-
- // Copy without DOM association.
- //
- type copy1 (*r);
-
- // Copy with DOM association.
- //
- type copy2 (*r, xml_schema::flags::keep_dom);
-}
-
-XMLPlatformUtils::Terminate ();
- </pre>
-
-
- <p>To obtain the corresponding DOM node from an object model node
- you will need to call the <code>_node</code> accessor function
- which returns a pointer to <code>DOMNode</code>. You can then query
- this DOM node's type and cast it to either <code>DOMAttr*</code>
- or <code>DOMElement*</code>. To obtain the corresponding object
- model node from a DOM node, the DOM user data API is used. The
- <code>xml_schema::dom::tree_node_key</code> variable contains
- the key for object model nodes. The following schema and code
- fragment show how to navigate from DOM to object model nodes
- and in the opposite direction:</p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="a" type="string"/>
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;element name="root" type="object"/>
- </pre>
-
- <pre class="c++">
-using namespace xercesc;
-
-XMLPlatformUtils::Initialize ();
-
-{
- // Parse XML to object model.
- //
- std::auto_ptr&lt;type> r (root (
- "root.xml",
- xml_schema::flags::keep_dom |
- xml_schema::flags::dont_initialize));
-
- DOMNode* n = r->_node ();
- assert (n->getNodeType () == DOMNode::ELEMENT_NODE);
- DOMElement* re = static_cast&lt;DOMElement*> (n);
-
- // Get the 'a' element. Note that it is not necessarily the
- // first child node of 'root' since there could be whitespace
- // nodes before it.
- //
- DOMElement* ae;
-
- for (n = re->getFirstChild (); n != 0; n = n->getNextSibling ())
- {
- if (n->getNodeType () == DOMNode::ELEMENT_NODE)
- {
- ae = static_cast&lt;DOMElement*> (n);
- break;
- }
- }
-
- // Get from the 'a' DOM element to xml_schema::string object model
- // node.
- //
- xml_schema::type&amp; t (
- *reinterpret_cast&lt;xml_schema::type*> (
- ae->getUserData (xml_schema::dom::tree_node_key)));
-
- xml_schema::string&amp; a (dynamic_cast&lt;xml_schema::string&amp;> (t));
-}
-
-XMLPlatformUtils::Terminate ();
- </pre>
-
- <p>The 'mixed' example which can be found in the XSD distribution
- shows how to handle the mixed content using DOM association.</p>
-
- <h2><a name="5.2">5.2 Binary Serialization</a></h2>
-
- <p>Besides reading from and writing to XML, the C++/Tree mapping
- also allows you to save the object model to and load it from a
- number of predefined as well as custom data representation
- formats. The predefined binary formats are CDR (Common Data
- Representation) and XDR (eXternal Data Representation). A
- custom format can easily be supported by providing
- insertion and extraction operators for basic types.</p>
-
- <p>Binary serialization saves only the data without any meta
- information or markup. As a result, saving to and loading
- from a binary representation can be an order of magnitude
- faster than parsing and serializing the same data in XML.
- Furthermore, the resulting representation is normally several
- times smaller than the equivalent XML representation. These
- properties make binary serialization ideal for internal data
- exchange and storage. A typical application that uses this
- facility stores the data and communicates within the
- system using a binary format and reads/writes the data
- in XML when communicating with the outside world.</p>
-
- <p>In order to request the generation of insertion operators and
- extraction constructors for a specific predefined or custom
- data representation stream, you will need to use the
- <code>--generate-insertion</code> and <code>--generate-extraction</code>
- compiler options. See the
- <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
- Compiler Command Line Manual</a> for more information.</p>
-
- <p>Once the insertion operators and extraction constructors are
- generated, you can use the <code>xml_schema::istream</code>
- and <code>xml_schema::ostream</code> wrapper stream templates
- to save the object model to and load it from a specific format.
- The following code fragment shows how to do this using ACE
- (Adaptive Communication Environment) CDR streams as an example:</p>
-
- <pre class="xml">
-&lt;complexType name="object">
- &lt;sequence>
- &lt;element name="a" type="string"/>
- &lt;element name="b" type="int"/>
- &lt;/sequence>
-&lt;/complexType>
-
-&lt;element name="root" type="object"/>
- </pre>
-
- <pre class="c++">
-// Parse XML to object model.
-//
-std::auto_ptr&lt;type> r (root ("root.xml"));
-
-// Save to a CDR stream.
-//
-ACE_OutputCDR ace_ocdr;
-xml_schema::ostream&lt;ACE_OutputCDR> ocdr (ace_ocdr);
-
-ocdr &lt;&lt; *r;
-
-// Load from a CDR stream.
-//
-ACE_InputCDR ace_icdr (buf, size);
-xml_schema::istream&lt;ACE_InputCDR> icdr (ace_icdr);
-
-std::auto_ptr&lt;object> copy (new object (icdr));
-
-// Serialize to XML.
-//
-root (std::cout, *copy);
- </pre>
-
- <p>The XSD distribution contains a number of examples that
- show how to save the object model to and load it from
- CDR, XDR, and a custom format.</p>
-
- <!-- Appendix A -->
-
-
- <h1><a name="A">Appendix A &mdash; Default and Fixed Values</a></h1>
-
- <p>The following table summarizes the effect of default and fixed
- values (specified with the <code>default</code> and <code>fixed</code>
- attributes, respectively) on attribute and element values. The
- <code>default</code> and <code>fixed</code> attributes are mutually
- exclusive. It is also worthwhile to note that the fixed value semantics
- is a superset of the default value semantics.
- </p>
-
- <!-- border="1" is necessary for html2ps -->
- <table id="default-fixed" border="1">
- <tr>
- <th></th>
- <th></th>
- <th colspan="2">default</th>
- <th colspan="2">fixed</th>
- </tr>
-
- <!-- element -->
-
- <tr>
- <th rowspan="4">element</th>
- <th rowspan="2">not present</th>
- <th>optional</th>
- <th>required</th>
- <th>optional</th>
- <th>required</th>
- </tr>
- <tr>
- <td>not present</td>
- <td>invalid instance</td>
- <td>not present</td>
- <td>invalid instance</td>
- </tr>
-
-
- <tr>
- <th>empty</th>
- <td colspan="2">default value is used</td>
- <td colspan="2">fixed value is used</td>
- </tr>
-
- <tr>
- <th>value</th>
- <td colspan="2">value is used</td>
- <td colspan="2">value is used provided it's the same as fixed</td>
- </tr>
-
- <!-- attribute -->
-
- <!-- element -->
-
- <tr>
- <th rowspan="4">attribute</th>
- <th rowspan="2">not present</th>
- <th>optional</th>
- <th>required</th>
- <th>optional</th>
- <th>required</th>
- </tr>
- <tr>
- <td>default value is used</td>
- <td>invalid schema</td>
- <td>fixed value is used</td>
- <td>invalid instance</td>
- </tr>
-
-
- <tr>
- <th>empty</th>
- <td colspan="2">empty value is used</td>
- <td colspan="2">empty value is used provided it's the same as fixed</td>
- </tr>
-
- <tr>
- <th>value</th>
- <td colspan="2">value is used</td>
- <td colspan="2">value is used provided it's the same as fixed</td>
- </tr>
-
- </table>
-
- </div>
-</div>
-
-
-</body>
-</html>