summaryrefslogtreecommitdiff
path: root/doc/cxx
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff.email>2024-03-06 10:24:08 +0100
committerJörg Frings-Fürst <debian@jff.email>2024-03-06 10:24:08 +0100
commitaad5ad9bf0c02aa4e79bc6b7d6c934612fff4026 (patch)
tree9cc224b059f248a6229ab0dcdc64eb4a73fa9800 /doc/cxx
parentc1034fc5e99197f507caf450aa15bc178698b26e (diff)
New upstream version 4.2.0upstream/4.2.0upstream
Diffstat (limited to 'doc/cxx')
-rw-r--r--doc/cxx/parser/guide/figure-1.pngbin0 -> 34195 bytes
-rw-r--r--doc/cxx/parser/guide/figure-1.svg373
-rw-r--r--doc/cxx/parser/guide/guide.html2ps.in65
-rw-r--r--doc/cxx/parser/guide/index.xhtml4163
-rw-r--r--doc/cxx/parser/guide/index.xhtml.in4163
-rw-r--r--doc/cxx/tree/guide/guide.html2ps.in65
-rw-r--r--doc/cxx/tree/guide/index.xhtml2736
-rw-r--r--doc/cxx/tree/guide/index.xhtml.in2736
-rw-r--r--doc/cxx/tree/manual/index.xhtml6826
-rw-r--r--doc/cxx/tree/manual/index.xhtml.in6826
-rw-r--r--doc/cxx/tree/manual/manual.html2ps.in66
11 files changed, 28019 insertions, 0 deletions
diff --git a/doc/cxx/parser/guide/figure-1.png b/doc/cxx/parser/guide/figure-1.png
new file mode 100644
index 0000000..15d1723
--- /dev/null
+++ b/doc/cxx/parser/guide/figure-1.png
Binary files differ
diff --git a/doc/cxx/parser/guide/figure-1.svg b/doc/cxx/parser/guide/figure-1.svg
new file mode 100644
index 0000000..d994a79
--- /dev/null
+++ b/doc/cxx/parser/guide/figure-1.svg
@@ -0,0 +1,373 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://web.resource.org/cc/"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="744.09448819"
+ height="1052.3622047"
+ id="svg2"
+ sodipodi:version="0.32"
+ inkscape:version="0.44.1"
+ sodipodi:docbase="/tmp"
+ sodipodi:docname="figure-1.svg"
+ inkscape:export-filename="/home/boris/tmp/figure-1.png"
+ inkscape:export-xdpi="76.195885"
+ inkscape:export-ydpi="76.195885">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow1Lend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Lend"
+ style="overflow:visible;">
+ <path
+ id="path2934"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
+ transform="scale(0.8) rotate(180) translate(12.5,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Dot_l"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Dot_l"
+ style="overflow:visible">
+ <path
+ id="path2875"
+ d="M -2.5,-1.0 C -2.5,1.7600000 -4.7400000,4.0 -7.5,4.0 C -10.260000,4.0 -12.5,1.7600000 -12.5,-1.0 C -12.5,-3.7600000 -10.260000,-6.0 -7.5,-6.0 C -4.7400000,-6.0 -2.5,-3.7600000 -2.5,-1.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;marker-end:none"
+ transform="scale(0.8) translate(7.4, 1)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Mend"
+ style="overflow:visible;">
+ <path
+ id="path2928"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;"
+ transform="scale(0.4) rotate(180) translate(10,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Dot_m"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Dot_m"
+ style="overflow:visible">
+ <path
+ id="path2872"
+ d="M -2.5,-1.0 C -2.5,1.7600000 -4.7400000,4.0 -7.5,4.0 C -10.260000,4.0 -12.5,1.7600000 -12.5,-1.0 C -12.5,-3.7600000 -10.260000,-6.0 -7.5,-6.0 C -4.7400000,-6.0 -2.5,-3.7600000 -2.5,-1.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;marker-end:none"
+ transform="scale(0.4) translate(7.4, 1)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Lstart"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow1Lstart"
+ style="overflow:visible">
+ <path
+ id="path2937"
+ d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+ transform="scale(0.8) translate(12.5,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow2Mend"
+ orient="auto"
+ refY="0.0"
+ refX="0.0"
+ id="Arrow2Mend"
+ style="overflow:visible;">
+ <path
+ id="path2910"
+ style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+ d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+ transform="scale(0.6) rotate(180) translate(0,0)" />
+ </marker>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ gridtolerance="10000"
+ guidetolerance="10"
+ objecttolerance="10"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="0.98994949"
+ inkscape:cx="328.23027"
+ inkscape:cy="733.01096"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ inkscape:window-width="1280"
+ inkscape:window-height="991"
+ inkscape:window-x="154"
+ inkscape:window-y="44" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1">
+ <g
+ id="g3902">
+ <rect
+ y="194.64178"
+ x="24.142784"
+ height="106.2678"
+ width="149.70432"
+ id="rect1872"
+ style="fill:#c5ddf8;fill-opacity:1;fill-rule:evenodd;stroke:#c5ddf8;stroke-width:5.29799986;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ sodipodi:linespacing="125%"
+ id="text3038"
+ y="219.99649"
+ x="28.284279"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;color:black;fill:black;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;font-family:Monospace"
+ xml:space="preserve"><tspan
+ y="219.99649"
+ x="28.284279"
+ id="tspan3064"
+ sodipodi:role="line">class people_pimpl</tspan><tspan
+ y="236.24649"
+ x="28.284279"
+ id="tspan3066"
+ sodipodi:role="line">{</tspan><tspan
+ y="252.49649"
+ x="28.284279"
+ id="tspan3068"
+ sodipodi:role="line"> void </tspan><tspan
+ y="268.74649"
+ x="28.284279"
+ id="tspan3070"
+ sodipodi:role="line"> person ();</tspan><tspan
+ y="284.99649"
+ x="28.284279"
+ id="tspan3072"
+ sodipodi:role="line">};</tspan></text>
+ </g>
+ <g
+ id="g3881">
+ <rect
+ y="124.93772"
+ x="252.43373"
+ height="245.67592"
+ width="180.01601"
+ id="rect5750"
+ style="fill:#c5ddf8;fill-opacity:1;fill-rule:evenodd;stroke:#c5ddf8;stroke-width:9.12976837;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ sodipodi:linespacing="100%"
+ id="text5752"
+ y="148.27567"
+ x="257.5889"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;color:black;fill:black;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;font-family:Monospace"
+ xml:space="preserve"><tspan
+ y="148.27567"
+ x="257.5889"
+ id="tspan5900"
+ sodipodi:role="line">class person_pimpl</tspan><tspan
+ y="161.27567"
+ x="257.5889"
+ id="tspan5902"
+ sodipodi:role="line">{</tspan><tspan
+ y="174.27567"
+ x="257.5889"
+ id="tspan5904"
+ sodipodi:role="line"> void</tspan><tspan
+ y="187.27567"
+ x="257.5889"
+ id="tspan5906"
+ sodipodi:role="line"> first_name (string);</tspan><tspan
+ y="200.27567"
+ x="257.5889"
+ id="tspan5908"
+ sodipodi:role="line" /><tspan
+ y="213.27567"
+ x="257.5889"
+ id="tspan5910"
+ sodipodi:role="line"> void</tspan><tspan
+ y="226.27567"
+ x="257.5889"
+ id="tspan5912"
+ sodipodi:role="line"> last_name (string);</tspan><tspan
+ y="239.27567"
+ x="257.5889"
+ id="tspan5914"
+ sodipodi:role="line" /><tspan
+ y="252.27567"
+ x="257.5889"
+ id="tspan5916"
+ sodipodi:role="line"> void</tspan><tspan
+ y="265.27567"
+ x="257.5889"
+ id="tspan5918"
+ sodipodi:role="line"> gender ();</tspan><tspan
+ y="278.27567"
+ x="257.5889"
+ id="tspan5920"
+ sodipodi:role="line" /><tspan
+ y="291.27567"
+ x="257.5889"
+ id="tspan5922"
+ sodipodi:role="line"> void</tspan><tspan
+ y="304.27567"
+ x="257.5889"
+ id="tspan5924"
+ sodipodi:role="line"> age (short);</tspan><tspan
+ y="317.27567"
+ x="257.5889"
+ id="tspan5926"
+ sodipodi:role="line"> </tspan><tspan
+ y="330.27567"
+ x="257.5889"
+ id="tspan5928"
+ sodipodi:role="line"> void</tspan><tspan
+ y="343.27567"
+ x="257.5889"
+ id="tspan5930"
+ sodipodi:role="line"> post_person ();</tspan><tspan
+ y="356.27567"
+ x="257.5889"
+ id="tspan5932"
+ sodipodi:role="line">};</tspan></text>
+ </g>
+ <g
+ id="g3845">
+ <rect
+ y="77.741814"
+ x="506.28357"
+ height="99.610825"
+ width="151.1286"
+ id="rect5955"
+ style="fill:#c5ddf8;fill-opacity:1;fill-rule:evenodd;stroke:#c5ddf8;stroke-width:5.69227886;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <flowRoot
+ transform="translate(-5.050762,12.10153)"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace"
+ id="flowRoot5957"
+ xml:space="preserve"><flowRegion
+ id="flowRegion5959"><rect
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace"
+ y="74.534515"
+ x="516.18793"
+ height="88.893425"
+ width="143.44167"
+ id="rect5961" /></flowRegion><flowPara
+ id="flowPara5965">class string_pimpl</flowPara><flowPara
+ id="flowPara5967">{</flowPara><flowPara
+ id="flowPara5969"> string</flowPara><flowPara
+ id="flowPara5971"> post_string ();</flowPara><flowPara
+ id="flowPara5973">};</flowPara><flowPara
+ id="flowPara5975" /></flowRoot> </g>
+ <g
+ id="g3857">
+ <rect
+ style="fill:#c5ddf8;fill-opacity:1;fill-rule:evenodd;stroke:#c5ddf8;stroke-width:5.69227886;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+ id="rect5977"
+ width="151.1286"
+ height="99.610825"
+ x="506.28357"
+ y="316.15808" />
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot5979"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace"
+ transform="translate(-5.050761,250.5178)"
+ inkscape:export-filename="/tmp/figure-1.png"
+ inkscape:export-xdpi="546.53815"
+ inkscape:export-ydpi="546.53815"><flowRegion
+ id="flowRegion5981"><rect
+ id="rect5983"
+ width="143.44167"
+ height="88.893425"
+ x="516.18793"
+ y="74.534515"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace" /></flowRegion><flowPara
+ id="flowPara5985">class short_pimpl</flowPara><flowPara
+ id="flowPara5987">{</flowPara><flowPara
+ id="flowPara5989"> short</flowPara><flowPara
+ id="flowPara5991"> post_short ();</flowPara><flowPara
+ id="flowPara5993">};</flowPara><flowPara
+ id="flowPara5995" /></flowRoot> </g>
+ <g
+ id="g3869">
+ <rect
+ style="fill:#c5ddf8;fill-opacity:1;fill-rule:evenodd;stroke:#c5ddf8;stroke-width:5.69227886;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+ id="rect6023"
+ width="151.1286"
+ height="99.610825"
+ x="505.7785"
+ y="196.93977" />
+ <flowRoot
+ xml:space="preserve"
+ id="flowRoot6025"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace"
+ transform="translate(-5.555838,129.2792)"><flowRegion
+ id="flowRegion6027"><rect
+ id="rect6029"
+ width="143.44167"
+ height="88.893425"
+ x="516.18793"
+ y="74.534515"
+ style="font-size:13px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Monospace" /></flowRegion><flowPara
+ id="flowPara6031">class gender_pimpl</flowPara><flowPara
+ id="flowPara6033">{</flowPara><flowPara
+ id="flowPara6035"> void</flowPara><flowPara
+ id="flowPara6037"> post_gender ();</flowPara><flowPara
+ id="flowPara6039">};</flowPara><flowPara
+ id="flowPara6041" /></flowRoot> </g>
+ <path
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;display:inline;marker-start:url(#Dot_l);marker-end:url(#Arrow1Lend)"
+ d="M 265.67011,339.69956 L 210.41811,339.34242 L 210.77124,264.14332 L 127.7843,264.4432"
+ id="path6051"
+ inkscape:connector-type="polyline"
+ sodipodi:nodetypes="cccs" />
+ <path
+ sodipodi:nodetypes="cccc"
+ inkscape:connector-type="polyline"
+ id="path6077"
+ d="M 518.20825,383.6412 L 471.23616,384.14628 L 471.4887,300.55615 L 368.70568,300.80869"
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Dot_l);marker-end:url(#Arrow1Lend);stroke-opacity:1;display:inline" />
+ <path
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Dot_l);marker-end:url(#Arrow1Lend);stroke-opacity:1;display:inline"
+ d="M 517.1981,262.42289 L 353.55339,262.42289"
+ id="path6081"
+ inkscape:connector-type="polyline"
+ sodipodi:nodetypes="cccs" />
+ <path
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Dot_l);marker-end:url(#Arrow1Lend);stroke-opacity:1;display:inline"
+ d="M 518.57143,145.93361 L 470.35714,146.14281 L 470.53572,183.07646 L 431.42857,183.79075"
+ id="path6089"
+ inkscape:connector-type="polyline"
+ sodipodi:nodetypes="cccc" />
+ <path
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Lend);stroke-opacity:1;display:inline"
+ d="M 470.46175,178.43361 L 470.89286,222.36218 L 423.21428,222.71932"
+ id="path6091"
+ inkscape:connector-type="polyline"
+ sodipodi:nodetypes="ccc" />
+ </g>
+</svg>
diff --git a/doc/cxx/parser/guide/guide.html2ps.in b/doc/cxx/parser/guide/guide.html2ps.in
new file mode 100644
index 0000000..8131487
--- /dev/null
+++ b/doc/cxx/parser/guide/guide.html2ps.in
@@ -0,0 +1,65 @@
+@@html2ps {
+ option {
+ toc: hb;
+ colour: 1;
+ hyphenate: 1;
+ titlepage: 1;
+ }
+
+ datefmt: "%B %Y";
+
+ titlepage {
+ content: "
+<div align=center>
+ <h1><big>C++/Parser Mapping</big></h1>
+ <h1><big>Getting Started Guide</big></h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+</div>
+ <p>Copyright &#169; @copyright@.</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/parser/guide/index.xhtml'>XHTML</a>,
+ <a href='https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.pdf'>PDF</a>, and
+ <a href='https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.ps'>PostScript</a>.</p>";
+ }
+
+ toc {
+ indent: 2em;
+ }
+
+ header {
+ odd-right: $H;
+ even-left: $H;
+ }
+
+ footer {
+ odd-left: $D;
+ odd-center: $T;
+ odd-right: $N;
+
+ even-left: $N;
+ even-center: $T;
+ even-right: $D;
+ }
+}
+
+body {
+ font-size: 12pt;
+ text-align: justify;
+}
+
+pre {
+ font-size: 10pt;
+}
diff --git a/doc/cxx/parser/guide/index.xhtml b/doc/cxx/parser/guide/index.xhtml
new file mode 100644
index 0000000..6964a14
--- /dev/null
+++ b/doc/cxx/parser/guide/index.xhtml
@@ -0,0 +1,4163 @@
+<?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++/Parser Mapping Getting Started Guide</title>
+
+ <meta name="copyright" content="&#169; 2005-2023 Code Synthesis"/>
+ <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,parser,validation"/>
+ <meta name="description" content="C++/Parser Mapping Getting Started Guide"/>
+
+ <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%;
+ line-height: 1.2em;
+ }
+
+ h2 {
+ font-weight : bold;
+ font-size : 150%;
+
+ padding-top : 0.8em;
+ }
+
+ h3 {
+ font-size : 140%;
+ 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;
+ }
+
+ #titlepage #first-title {
+ padding: 1em 0 0.4em 0;
+ }
+
+ #titlepage #second-title {
+ padding: 0.4em 0 2em 0;
+ }
+
+ /* Lists */
+ ul.list li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+ ol.steps {
+ padding-left : 1.8em;
+ }
+
+ ol.steps li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+
+ div.img {
+ text-align: center;
+ padding: 2em 0 2em 0;
+ }
+
+ /* */
+ dl dt {
+ padding : 0.8em 0 0 0;
+ }
+
+ /* 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;
+ }
+
+ /* XML Schema features table. */
+ #features {
+ margin: 2em 0 2em 0;
+
+ border-collapse : collapse;
+ border : 1px solid;
+ border-color : #000000;
+
+ font-size : 11px;
+ line-height : 14px;
+ }
+
+ #features th, #features td {
+ border: 1px solid;
+ padding : 0.6em 0.6em 0.6em 0.6em;
+ }
+
+ #features th {
+ background : #cde8f6;
+ }
+
+ #features td {
+ text-align: left;
+ }
+
+
+ /* 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 class="title" id="first-title">C++/Parser Mapping</div>
+ <div class="title" id="second-title">Getting Started Guide</div>
+
+ <p>Copyright &#169; 2005-2023 Code Synthesis.</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/parser/guide/index.xhtml">XHTML</a>,
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.pdf">PDF</a>, and
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.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>
+ <table class="toc">
+ <tr><th>1.1</th><td><a href="#1.1">Mapping Overview</a></td></tr>
+ <tr><th>1.2</th><td><a href="#1.2">Benefits</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>2</th><td><a href="#2">Hello World Example</a>
+ <table class="toc">
+ <tr><th>2.1</th><td><a href="#2.1">Writing XML Document and Schema</a></td></tr>
+ <tr><th>2.2</th><td><a href="#2.2">Translating Schema to C++</a></td></tr>
+ <tr><th>2.3</th><td><a href="#2.3">Implementing Application Logic</a></td></tr>
+ <tr><th>2.4</th><td><a href="#2.4">Compiling and Running</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>3</th><td><a href="#3">Parser Skeletons</a>
+ <table class="toc">
+ <tr><th>3.1</th><td><a href="#3.1">Implementing the Gender Parser</a></td></tr>
+ <tr><th>3.2</th><td><a href="#3.2">Implementing the Person Parser</a></td></tr>
+ <tr><th>3.3</th><td><a href="#3.3">Implementing the People Parser</a></td></tr>
+ <tr><th>3.4</th><td><a href="#3.4">Connecting the Parsers Together</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>4</th><td><a href="#4">Type Maps</a>
+ <table class="toc">
+ <tr><th>4.1</th><td><a href="#4.1">Object Model</a></td></tr>
+ <tr><th>4.2</th><td><a href="#4.2">Type Map File Format</a></td></tr>
+ <tr><th>4.3</th><td><a href="#4.3">Parser Implementations</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>5</th><td><a href="#5">Mapping Configuration</a>
+ <table class="toc">
+ <tr><th>5.1</th><td><a href="#5.1">C++ Standard</a></td></tr>
+ <tr><th>5.2</th><td><a href="#5.2">Character Type and Encoding</a></td></tr>
+ <tr><th>5.3</th><td><a href="#5.3">Underlying XML Parser</a></td></tr>
+ <tr><th>5.4</th><td><a href="#5.4">XML Schema Validation</a></td></tr>
+ <tr><th>5.5</th><td><a href="#5.5">Support for Polymorphism</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>6</th><td><a href="#6">Built-In XML Schema Type Parsers</a>
+ <table class="toc">
+ <tr><th>6.1</th><td><a href="#6.1"><code>QName</code> Parser</a></td></tr>
+ <tr><th>6.2</th><td><a href="#6.2"><code>NMTOKENS</code> and <code>IDREFS</code> Parsers</a></td></tr>
+ <tr><th>6.3</th><td><a href="#6.3"><code>base64Binary</code> and <code>hexBinary</code> Parsers</a></td></tr>
+ <tr><th>6.4</th><td><a href="#6.4">Time Zone Representation</a></td></tr>
+ <tr><th>6.5</th><td><a href="#6.5"><code>date</code> Parser</a></td></tr>
+ <tr><th>6.6</th><td><a href="#6.6"><code>dateTime</code> Parser</a></td></tr>
+ <tr><th>6.7</th><td><a href="#6.7"><code>duration</code> Parser</a></td></tr>
+ <tr><th>6.8</th><td><a href="#6.8"><code>gDay</code> Parser</a></td></tr>
+ <tr><th>6.9</th><td><a href="#6.9"><code>gMonth</code> Parser</a></td></tr>
+ <tr><th>6.10</th><td><a href="#6.10"><code>gMonthDay</code> Parser</a></td></tr>
+ <tr><th>6.11</th><td><a href="#6.11"><code>gYear</code> Parser</a></td></tr>
+ <tr><th>6.12</th><td><a href="#6.12"><code>gYearMonth</code> Parser</a></td></tr>
+ <tr><th>6.13</th><td><a href="#6.13"><code>time</code> Parser</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>7</th><td><a href="#7">Document Parser and Error Handling</a>
+ <table class="toc">
+ <tr><th>7.1</th><td><a href="#7.1">Xerces-C++ Document Parser</a></td></tr>
+ <tr><th>7.2</th><td><a href="#7.2">Expat Document Parser</a></td></tr>
+ <tr><th>7.3</th><td><a href="#7.3">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th></th><td><a href="#A">Appendix A &mdash; Supported XML Schema Constructs</a></td>
+ </tr>
+
+ </table>
+ </div>
+
+ <h1><a name="0">Preface</a></h1>
+
+ <h2><a name="0.1">About This Document</a></h2>
+
+ <p>The goal of this document is to provide you with an understanding of
+ the C++/Parser programming model and allow you to efficiently evaluate
+ XSD against your project's technical requirements. As such, this
+ document is intended for C++ developers and software architects
+ who are looking for an XML processing solution. Prior experience
+ with XML and C++ is required to understand this document. Basic
+ understanding of XML Schema is advantageous but not expected
+ or required.
+ </p>
+
+
+ <h2><a name="0.2">More Information</a></h2>
+
+ <p>Beyond this guide, you may also find the following sources of
+ information useful:</p>
+
+ <ul class="list">
+ <li><a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a></li>
+
+ <li>The <code>cxx/parser/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</li>
+
+ <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a>
+ mailing list is the place to ask technical questions about XSD and the C++/Parser mapping.
+ Furthermore, the <a href="https://www.codesynthesis.com/pipermail/xsd-users/">archives</a>
+ may already have answers to some of your questions.</li>
+
+ </ul>
+
+ <!-- Introduction -->
+
+ <h1><a name="1">1 Introduction</a></h1>
+
+ <p>Welcome to CodeSynthesis XSD and the C++/Parser mapping. XSD is a
+ cross-platform W3C XML Schema to C++ data binding compiler. C++/Parser
+ is a W3C XML Schema to C++ mapping that represents an XML vocabulary
+ as a set of parser skeletons which you can implement to perform XML
+ processing as required by your application logic.
+ </p>
+
+ <h2><a name="1.1">1.1 Mapping Overview</a></h2>
+
+ <p>The C++/Parser mapping provides event-driven, stream-oriented
+ XML parsing, XML Schema validation, and C++ data binding. It was
+ specifically designed and optimized for high performance and
+ small footprint. Based on the static analysis of the schemas, XSD
+ generates compact, highly-optimized hierarchical state machines
+ that combine data extraction, validation, and even dispatching
+ in a single step. As a result, the generated code is typically
+ 2-10 times faster than general-purpose validating XML parsers
+ while maintaining the lowest static and dynamic memory footprints.
+ </p>
+
+ <p>To speed up application development, the C++/Parser mapping
+ can be instructed to generate sample parser implementations
+ and a test driver which can then be filled with the application
+ logic code. The mapping also provides a wide range of
+ mechanisms for controlling and customizing the generated code.</p>
+
+ <p>The next chapter shows how to create a simple application that uses
+ the C++/Parser mapping to parse, validate, and extract data from a
+ simple XML document. The following chapters show how to
+ use the C++/Parser mapping in more detail.</p>
+
+ <h2><a name="1.2">1.2 Benefits</a></h2>
+
+ <p>Traditional XML access APIs such as Document Object Model (DOM)
+ or Simple API for XML (SAX) have a number of drawbacks that
+ make them less suitable for creating robust and maintainable
+ XML processing applications. These drawbacks include:
+ </p>
+
+ <ul class="list">
+ <li>Generic representation of XML in terms of elements, attributes,
+ and text forces an application developer to write a substantial
+ amount of bridging code that identifies and transforms pieces
+ of information encoded in XML to a representation more suitable
+ for consumption by the application logic.</li>
+
+ <li>String-based flow control defers error detection to runtime.
+ It also reduces code readability and maintainability.</li>
+
+ <li>Lack of type safety because the data is represented
+ as text.</li>
+
+ <li>Resulting applications are hard to debug, change, and
+ maintain.</li>
+ </ul>
+
+ <p>In contrast, statically-typed, vocabulary-specific parser
+ skeletons produced by the C++/Parser mapping allow you to
+ operate in your domain terms instead of the generic elements,
+ attributes, and text. Static typing helps catch errors at
+ compile-time rather than at run-time. Automatic code generation
+ frees you for more interesting tasks (such as doing something
+ useful with the information stored in the XML documents) and
+ minimizes the effort needed to adapt your applications to
+ changes in the document structure. To summarize, the C++/Parser
+ mapping has the following key advantages over generic XML
+ access APIs:</p>
+
+ <ul class="list">
+ <li><b>Ease of use.</b> The generated code hides all the complexity
+ associated with recreating the document structure, maintaining the
+ dispatch state, and converting the data from the text representation
+ to data types suitable for manipulation by the application logic.
+ Parser skeletons also provide a convenient mechanism for building
+ custom in-memory representations.</li>
+
+ <li><b>Natural representation.</b> The generated parser skeletons
+ implement parser callbacks as virtual functions with names
+ corresponding to elements and attributes in XML. As a result,
+ you process the XML data using your domain vocabulary instead
+ of generic elements, attributes, and text.
+ </li>
+
+ <li><b>Concise code.</b> With a separate parser skeleton for each
+ XML Schema type, the application implementation is
+ simpler and thus easier to read and understand.</li>
+
+ <li><b>Safety.</b> The XML data is delivered to parser callbacks as
+ statically typed objects. The parser callbacks themselves are virtual
+ functions. This helps catch programming errors at compile-time
+ rather than at runtime.</li>
+
+ <li><b>Maintainability.</b> Automatic code generation minimizes the
+ effort needed to adapt the application to changes in the
+ document structure. With static typing, the C++ compiler
+ can pin-point the places in the application code that need to be
+ changed.</li>
+
+ <li><b>Efficiency.</b> The generated parser skeletons combine
+ data extraction, validation, and even dispatching in a single
+ step. This makes them much more efficient than traditional
+ architectures with separate stages for validation and data
+ extraction/dispatch.</li>
+ </ul>
+
+ <!-- Hello World Parser -->
+
+
+ <h1><a name="2">2 Hello World Example</a></h1>
+
+ <p>In this chapter we will examine how to parse a very simple XML
+ document using the XSD-generated C++/Parser skeletons.
+ The code presented in this chapter is based on the <code>hello</code>
+ example which can be found in the <code>cxx/parser/</code> directory in
+ the <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</p>
+
+ <h2><a name="2.1">2.1 Writing XML Document and Schema</a></h2>
+
+ <p>First, we need to get an idea about the structure
+ of the XML documents we are going to process. Our
+ <code>hello.xml</code>, for example, could look like this:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello>
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>Then we can write a description of the above XML in the
+ XML Schema language and save it into <code>hello.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello">
+ &lt;xs:sequence>
+ &lt;xs:element name="greeting" type="xs:string"/>
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Even if you are not familiar with XML Schema, it
+ should be easy to connect declarations in <code>hello.xsd</code>
+ to elements in <code>hello.xml</code>. The <code>hello</code> type
+ is defined as a sequence of the nested <code>greeting</code> and
+ <code>name</code> elements. Note that the term sequence in XML
+ Schema means that elements should appear in a particular order
+ as opposed to appearing multiple times. The <code>name</code>
+ element has its <code>maxOccurs</code> property set to
+ <code>unbounded</code> which means it can appear multiple times
+ in an XML document. Finally, the globally-defined <code>hello</code>
+ element prescribes the root element for our vocabulary. For an
+ easily-approachable introduction to XML Schema refer to
+ <a href="http://www.w3.org/TR/xmlschema-0/">XML Schema Part 0:
+ Primer</a>.</p>
+
+ <p>The above schema is a specification of our XML vocabulary; it tells
+ everybody what valid documents of our XML-based language should look
+ like. The next step is to compile this schema to generate
+ the object model and parsing functions.</p>
+
+ <h2><a name="2.2">2.2 Translating Schema to C++</a></h2>
+
+ <p>Now we are ready to translate our <code>hello.xsd</code> to C++ parser
+ skeletons. To do this we invoke the XSD compiler from a terminal
+ (UNIX) or a command prompt (Windows):
+ </p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --xml-parser expat hello.xsd
+ </pre>
+
+ <p>The <code>--xml-parser</code> option indicates that we want to
+ use Expat as the underlying XML parser (see <a href="#5.3">Section
+ 5.3, "Underlying XML Parser"</a>). The XSD compiler produces two
+ C++ files: <code>hello-pskel.hxx</code> and <code>hello-pskel.cxx</code>.
+ The following code fragment is taken from <code>hello-pskel.hxx</code>;
+ it should give you an idea about what gets generated:
+ </p>
+
+ <pre class="c++">
+class hello_pskel
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ greeting (const std::string&amp;);
+
+ virtual void
+ name (const std::string&amp;);
+
+ virtual void
+ post_hello ();
+
+ // Parser construction API.
+ //
+ void
+ greeting_parser (xml_schema::string_pskel&amp;);
+
+ void
+ name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ parsers (xml_schema::string_pskel&amp; /* greeting */,
+ xml_schema::string_pskel&amp; /* name */);
+
+private:
+ ...
+};
+ </pre>
+
+ <p>The first four member functions shown above are called parser
+ callbacks. You would normally override them in your implementation
+ of the parser to do something useful. Let's go through all of
+ them one by one.</p>
+
+ <p>The <code>pre()</code> function is an initialization callback. It is
+ called when a new element of type <code>hello</code> is about
+ to be parsed. You would normally use this function to allocate a new
+ instance of the resulting type or clear accumulators that are used
+ to gather information during parsing. The default implementation
+ of this function does nothing.</p>
+
+ <p>The <code>post_hello()</code> function is a finalization callback. Its
+ name is constructed by adding the parser skeleton name to the
+ <code>post_</code> prefix. The finalization callback is called when
+ parsing of the element is complete and the result, if any, should
+ be returned. Note that in our case the return type of
+ <code>post_hello()</code> is <code>void</code> which means there
+ is nothing to return. More on parser return types later.
+ </p>
+
+ <p>You may be wondering why the finalization callback is called
+ <code>post_hello()</code> instead of <code>post()</code> just
+ like <code>pre()</code>. The reason for this is that
+ finalization callbacks can have different return types and
+ result in function signature clashes across inheritance
+ hierarchies. To prevent this the signatures of finalization
+ callbacks are made unique by adding the type name to their names.</p>
+
+ <p>The <code>greeting()</code> and <code>name()</code> functions are
+ called when the <code>greeting</code> and <code>name</code> elements
+ have been parsed, respectively. Their arguments are of type
+ <code>std::string</code> and contain the data extracted from XML.</p>
+
+ <p>The last three functions are for connecting parsers to each other.
+ For example, there is a predefined parser for built-in XML Schema type
+ <code>string</code> in the XSD runtime. We will be using
+ it to parse the contents of <code>greeting</code> and
+ <code>name</code> elements, as shown in the next section.</p>
+
+ <h2><a name="2.3">2.3 Implementing Application Logic</a></h2>
+
+ <p>At this point we have all the parts we need to do something useful
+ with the information stored in our XML document. The first step is
+ to implement the parser:
+ </p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello-pskel.hxx"
+
+class hello_pimpl: public hello_pskel
+{
+public:
+ virtual void
+ greeting (const std::string&amp; g)
+ {
+ greeting_ = g;
+ }
+
+ virtual void
+ name (const std::string&amp; n)
+ {
+ std::cout &lt;&lt; greeting_ &lt;&lt; ", " &lt;&lt; n &lt;&lt; "!" &lt;&lt; std::endl;
+ }
+
+private:
+ std::string greeting_;
+};
+ </pre>
+
+ <p>We left both <code>pre()</code> and <code>post_hello()</code> with the
+ default implementations; we don't have anything to initialize or
+ return. The rest is pretty straightforward: we store the greeting
+ in a member variable and later, when parsing names, use it to
+ say hello.</p>
+
+ <p>An observant reader my ask what happens if the <code>name</code>
+ element comes before <code>greeting</code>? Don't we need to
+ make sure <code>greeting_</code> was initialized and report
+ an error otherwise? The answer is no, we don't have to do
+ any of this. The <code>hello_pskel</code> parser skeleton
+ performs validation of XML according to the schema from which
+ it was generated. As a result, it will check the order
+ of the <code>greeting</code> and <code>name</code> elements
+ and report an error if it is violated.</p>
+
+ <p>Now it is time to put this parser implementation to work:</p>
+
+ <pre class="c++">
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ // Construct the parser.
+ //
+ xml_schema::string_pimpl string_p;
+ hello_pimpl hello_p;
+
+ hello_p.greeting_parser (string_p);
+ hello_p.name_parser (string_p);
+
+ // Parse the XML instance.
+ //
+ xml_schema::document doc_p (hello_p, "hello");
+
+ hello_p.pre ();
+ doc_p.parse (argv[1]);
+ hello_p.post_hello ();
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>The first part of this code snippet instantiates individual parsers
+ and assembles them into a complete vocabulary parser.
+ <code>xml_schema::string_pimpl</code> is an implementation of a parser
+ for built-in XML Schema type <code>string</code>. It is provided by
+ the XSD runtime along with parsers for other built-in types (for
+ more information on the built-in parsers see <a href="#6">Chapter 6,
+ "Built-In XML Schema Type Parsers"</a>). We use <code>string_pimpl</code>
+ to parse the <code>greeting</code> and <code>name</code> elements as
+ indicated by the calls to <code>greeting_parser()</code> and
+ <code>name_parser()</code>.
+ </p>
+
+ <p>Then we instantiate a document parser (<code>doc_p</code>). The
+ first argument to its constructor is the parser for
+ the root element (<code>hello_p</code> in our case). The
+ second argument is the root element name.
+ </p>
+
+ <p>The final piece is the calls to <code>pre()</code>, <code>parse()</code>,
+ and <code>post_hello()</code>. The call to <code>parse()</code>
+ perform the actual XML parsing while the calls to <code>pre()</code> and
+ <code>post_hello()</code> make sure that the parser for the root
+ element can perform proper initialization and cleanup.</p>
+
+ <p>While our parser implementation and test driver are pretty small and
+ easy to write by hand, for bigger XML vocabularies it can be a
+ substantial effort. To help with this task XSD can automatically
+ generate sample parser implementations and a test driver from your
+ schemas. You can request the generation of a sample implementation with
+ empty function bodies by specifying the <code>--generate-noop-impl</code>
+ option. Or you can generate a sample implementation that prints the
+ data store in XML by using the <code>--generate-print-impl</code>
+ option. To request the generation of a test driver you can use the
+ <code>--generate-test-driver</code> option. For more information
+ on these options refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>. The <code>'generated'</code> example
+ in the <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ shows the sample implementation generation feature in action.</p>
+
+
+ <h2><a name="2.4">2.4 Compiling and Running</a></h2>
+
+ <p>After saving all the parts from the previous section in
+ <code>driver.cxx</code>, we are ready to compile our first
+ application and run it on the test XML document. On a UNIX
+ system this can be done with the following commands:
+ </p>
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx hello-pskel.cxx
+$ c++ -std=c++11 -o driver driver.o hello-pskel.o -lexpat
+$ ./driver hello.xml
+Hello, sun!
+Hello, moon!
+Hello, world!
+ </pre>
+
+ <p>Here <code>.../libxsd</code> represents the path to the
+ <a href="https://cppget.org/libxsd">libxsd</a> package root
+ directory. We can also test the error handling. To test XML
+ well-formedness checking, we can try to parse
+ <code>hello-pskel.hxx</code>:</p>
+
+ <pre class="terminal">
+$ ./driver hello-pskel.hxx
+hello-pskel.hxx:1:0: not well-formed (invalid token)
+ </pre>
+
+ <p>We can also try to parse a valid XML but not from our
+ vocabulary, for example <code>hello.xsd</code>:</p>
+
+ <pre class="terminal">
+$ ./driver hello.xsd
+hello.xsd:2:0: expected element 'hello' instead of
+'http://www.w3.org/2001/XMLSchema#schema'
+ </pre>
+
+
+ <!-- Chapater 3 -->
+
+
+ <h1><a name="3">3 Parser Skeletons</a></h1>
+
+ <p>As we have seen in the previous chapter, the XSD compiler generates
+ a parser skeleton class for each type defined in XML Schema. In
+ this chapter we will take a closer look at different functions
+ that comprise a parser skeleton as well as the way to connect
+ our implementations of these parser skeletons to create a complete
+ parser.</p>
+
+ <p>In this and subsequent chapters we will use the following schema
+ that describes a collection of person records. We save it in
+ <code>people.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:simpleType name="gender">
+ &lt;xs:restriction base="xs:string">
+ &lt;xs:enumeration value="male"/>
+ &lt;xs:enumeration value="female"/>
+ &lt;/xs:restriction>
+ &lt;/xs:simpleType>
+
+ &lt;xs:complexType name="person">
+ &lt;xs:sequence>
+ &lt;xs:element name="first-name" type="xs:string"/>
+ &lt;xs:element name="last-name" type="xs:string"/>
+ &lt;xs:element name="gender" type="gender"/>
+ &lt;xs:element name="age" type="xs:short"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:complexType name="people">
+ &lt;xs:sequence>
+ &lt;xs:element name="person" type="person" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="people" type="people"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>A sample XML instance to go along with this schema is saved
+ in <code>people.xml</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people>
+ &lt;person>
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+ &lt;person>
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+&lt;/people>
+ </pre>
+
+ <p>Compiling <code>people.xsd</code> with the XSD compiler results
+ in three parser skeletons being generated: <code>gender_pskel</code>,
+ <code>person_pskel</code>, and <code>people_pskel</code>. We are going
+ to examine and implement each of them in the subsequent sections.</p>
+
+ <h2><a name="3.1">3.1 Implementing the Gender Parser</a></h2>
+
+ <p>The generated <code>gender_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class gender_pskel: public virtual xml_schema::string_pskel
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ post_gender ();
+};
+ </pre>
+
+ <p>Notice that <code>gender_pskel</code> inherits from
+ <code>xml_schema::string_skel</code> which is a parser skeleton
+ for built-in XML Schema type <code>string</code> and is
+ predefined in the XSD runtime library. This is an example
+ of the general rule that parser skeletons follow: if a type
+ in XML Schema inherits from another then there will be an
+ equivalent inheritance between the corresponding parser
+ skeleton classes.</p>
+
+ <p>The <code>pre()</code> and <code>post_gender()</code> callbacks
+ should look familiar from the previous chapter. Let's now
+ implement the parser. Our implementation will simply print
+ the gender to <code>cout</code>:</p>
+
+
+ <pre class="c++">
+class gender_pimpl: public gender_pskel,
+ public xml_schema::string_pimpl
+{
+public:
+ virtual void
+ post_gender ()
+ {
+ std::string s = post_string ();
+ cout &lt;&lt; "gender: " &lt;&lt; s &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>While the code is quite short, there is a lot going on. First,
+ notice that we are inheriting from <code>gender_pskel</code> <em>and</em>
+ from <code>xml_schema::string_pimpl</code>. We've encountered
+ <code>xml_schema::string_pimpl</code> already; it is an
+ implementation of the <code>xml_schema::string_pskel</code> parser
+ skeleton for built-in XML Schema type <code>string</code>.</p>
+
+ <p>This is another common theme in the C++/Parser programming model:
+ reusing implementations of the base parsers in the derived ones with
+ the C++ mixin idiom. In our case, <code>string_pimpl</code> will
+ do all the dirty work of extracting the data and we can just get
+ it at the end with the call to <code>post_string()</code>.</p>
+
+ <p>In case you are curious, here is what
+ <code>xml_schema::string_pskel</code> and
+ <code>xml_schema::string_pimpl</code> look like:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class string_pskel: public simple_content
+ {
+ public:
+ virtual std::string
+ post_string () = 0;
+ };
+
+ class string_pimpl: public virtual string_pskel
+ {
+ public:
+ virtual void
+ _pre ();
+
+ virtual void
+ _characters (const xml_schema::ro_string&amp;);
+
+ virtual std::string
+ post_string ();
+
+ protected:
+ std::string str_;
+ };
+}
+ </pre>
+
+ <p>There are three new pieces in this code that we haven't seen yet.
+ They are the <code>simple_content</code> class as well as
+ the <code>_pre()</code> and <code>_characters()</code> functions.
+ The <code>simple_content</code> class is defined in the XSD
+ runtime and is a base class for all parser skeletons that conform
+ to the simple content model in XML Schema. Types with the
+ simple content model cannot have nested elements&mdash;only text
+ and attributes. There is also the <code>complex_content</code>
+ class which corresponds to the complex content mode (types with
+ nested elements, for example, <code>person</code> from
+ <code>people.xsd</code>).</p>
+
+ <p>The <code>_pre()</code> function is a parser callback. Remember we
+ talked about the <code>pre()</code> and <code>post_*()</code> callbacks
+ in the previous chapter? There are actually two more callbacks
+ with similar roles: <code>_pre()</code> and <code>_post ()</code>.
+ As a result, each parser skeleton has four special callbacks:</p>
+
+ <pre class="c++">
+ virtual void
+ pre ();
+
+ virtual void
+ _pre ();
+
+ virtual void
+ _post ();
+
+ virtual void
+ post_name ();
+ </pre>
+
+ <p><code>pre()</code> and <code>_pre()</code> are initialization
+ callbacks. They get called in that order before a new instance of the type
+ is about to be parsed. The difference between <code>pre()</code> and
+ <code>_pre()</code> is conventional: <code>pre()</code> can
+ be completely overridden by a derived parser. The derived
+ parser can also override <code>_pre()</code> but has to always call
+ the original version. This allows you to partition initialization
+ into customizable and required parts.</p>
+
+ <p>Similarly, <code>_post()</code> and <code>post_name()</code> are
+ finalization callbacks with exactly the same semantics:
+ <code>post_name()</code> can be completely overridden by the derived
+ parser while the original <code>_post()</code> should always be called.
+ </p>
+
+ <p>The final bit we need to discuss in this section is the
+ <code>_characters()</code> function. As you might have guessed, it
+ is also a callback. A low-level one that delivers raw character content
+ for the type being parsed. You will seldom need to use this callback
+ directly. Using implementations for the built-in parsers provided by
+ the XSD runtime is usually a simpler and more convenient
+ alternative.</p>
+
+ <p>At this point you might be wondering why some <code>post_*()</code>
+ callbacks, for example <code>post_string()</code>, return some data
+ while others, for example <code>post_gender()</code>, have
+ <code>void</code> as a return type. This is a valid concern
+ and it will be addressed in the next chapter.</p>
+
+ <h2><a name="3.2">3.2 Implementing the Person Parser</a></h2>
+
+ <p>The generated <code>person_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class person_pskel: public xml_schema::complex_content
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ first_name (const std::string&amp;);
+
+ virtual void
+ last_name (const std::string&amp;);
+
+ virtual void
+ gender ();
+
+ virtual void
+ age (short);
+
+ virtual void
+ post_person ();
+
+ // Parser construction API.
+ //
+ void
+ first_name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ last_name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ gender_parser (gender_pskel&amp;);
+
+ void
+ age_parser (xml_schema::short_pskel&amp;);
+
+ void
+ parsers (xml_schema::string_pskel&amp; /* first-name */,
+ xml_schema::string_pskel&amp; /* last-name */,
+ gender_pskel&amp; /* gender */,
+ xml_schema::short_pskel&amp; /* age */);
+};
+ </pre>
+
+
+ <p>As you can see, we have a parser callback for each of the nested
+ elements found in the <code>person</code> XML Schema type.
+ The implementation of this parser is straightforward:</p>
+
+ <pre class="c++">
+class person_pimpl: public person_pskel
+{
+public:
+ virtual void
+ first_name (const std::string&amp; n)
+ {
+ cout &lt;&lt; "first: " &lt;&lt; f &lt;&lt; endl;
+ }
+
+ virtual void
+ last_name (const std::string&amp; l)
+ {
+ cout &lt;&lt; "last: " &lt;&lt; l &lt;&lt; endl;
+ }
+
+ virtual void
+ age (short a)
+ {
+ cout &lt;&lt; "age: " &lt;&lt; a &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Notice that we didn't override the <code>gender()</code> callback
+ because all the printing is done by <code>gender_pimpl</code>.</p>
+
+
+ <h2><a name="3.3">3.3 Implementing the People Parser</a></h2>
+
+ <p>The generated <code>people_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class people_pskel: public xml_schema::complex_content
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ person ();
+
+ virtual void
+ post_people ();
+
+ // Parser construction API.
+ //
+ void
+ person_parser (person_pskel&amp;);
+
+ void
+ parsers (person_pskel&amp; /* person */);
+};
+ </pre>
+
+ <p>The <code>person()</code> callback will be called after parsing each
+ <code>person</code> element. While <code>person_pimpl</code> does
+ all the printing, one useful thing we can do in this callback is to
+ print an extra newline after each person record so that our
+ output is more readable:</p>
+
+ <pre class="c++">
+class people_pimpl: public people_pskel
+{
+public:
+ virtual void
+ person ()
+ {
+ cout &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Now it is time to put everything together.</p>
+
+
+ <h2><a name="3.4">3.4 Connecting the Parsers Together</a></h2>
+
+ <p>At this point we have all the individual parsers implemented
+ and can proceed to assemble them into a complete parser
+ for our XML vocabulary. The first step is to instantiate
+ all the individual parsers that we will need:</p>
+
+ <pre class="c++">
+xml_schema::short_pimpl short_p;
+xml_schema::string_pimpl string_p;
+
+gender_pimpl gender_p;
+person_pimpl person_p;
+people_pimpl people_p;
+ </pre>
+
+ <p>Notice that our schema uses two built-in XML Schema types:
+ <code>string</code> for the <code>first-name</code> and
+ <code>last-name</code> elements as well as <code>short</code>
+ for <code>age</code>. We will use predefined parsers that
+ come with the XSD runtime to handle these types. The next
+ step is to connect all the individual parsers. We do this
+ with the help of functions defined in the parser
+ skeletons and marked with the "Parser Construction API"
+ comment. One way to do it is to connect each individual
+ parser by calling the <code>*_parser()</code> functions:</p>
+
+ <pre class="c++">
+person_p.first_name_parser (string_p);
+person_p.last_name_parser (string_p);
+person_p.gender_parser (gender_p);
+person_p.age_parser (short_p);
+
+people_p.person_parser (person_p);
+ </pre>
+
+ <p>You might be wondering what happens if you do not provide
+ a parser by not calling one of the <code>*_parser()</code> functions.
+ In that case the corresponding XML content will be skipped,
+ including validation. This is an efficient way to ignore parts
+ of the document that you are not interested in.</p>
+
+
+ <p>An alternative, shorter, way to connect the parsers is by using
+ the <code>parsers()</code> functions which connects all the parsers
+ for a given type at once:</p>
+
+ <pre class="c++">
+person_p.parsers (string_p, string_p, gender_p, short_p);
+people_p.parsers (person_p);
+ </pre>
+
+ <p>The following figure illustrates the resulting connections. Notice
+ the correspondence between return types of the <code>post_*()</code>
+ functions and argument types of element callbacks that are connected
+ by the arrows.</p>
+
+ <!-- align=center is needed for html2ps -->
+ <div class="img" align="center"><img src="figure-1.png"/></div>
+
+ <p>The last step is the construction of the document parser and
+ invocation of the complete parser on our sample XML instance:</p>
+
+ <pre class="c++">
+xml_schema::document doc_p (people_p, "people");
+
+people_p.pre ();
+doc_p.parse ("people.xml");
+people_p.post_people ();
+ </pre>
+
+ <p>Let's consider <code>xml_schema::document</code> in
+ more detail. While the exact definition of this class
+ varies depending on the underlying parser selected,
+ here is the common part:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class document
+ {
+ public:
+ document (xml_schema::parser_base&amp;,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (xml_schema::parser_base&amp;,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ void
+ parse (const std::string&amp; file);
+
+ void
+ parse (std::istream&amp;);
+
+ ...
+
+ };
+}
+ </pre>
+
+ <p><code>xml_schema::document</code> is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element (<code>people_impl</code>
+ in our case). Because a type parser is only concerned with
+ the element's content and not with the element's name, we need
+ to specify the root element's name somewhere. That's
+ what is passed as the second and third arguments to the
+ <code>document</code>'s constructors.</p>
+
+ <p>There are also two overloaded <code>parse()</code> functions
+ defined in the <code>document</code> class (there are actually
+ more but the others are specific to the underlying XML parser).
+ The first version parses a local file identified by a name. The
+ second version reads the data from an input stream. For more
+ information on the <code>xml_schema::document</code> class
+ refer to <a href="#7">Chapter 7, "Document Parser and Error
+ Handling"</a>.</p>
+
+ <p>Let's now consider a step-by-step list of actions that happen
+ as we parse through <code>people.xml</code>. The content of
+ <code>people.xml</code> is repeated below for convenience.</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people>
+ &lt;person>
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+ &lt;person>
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+&lt;/people>
+ </pre>
+
+
+ <ol class="steps">
+ <li><code>people_p.pre()</code> is called from
+ <code>main()</code>. We did not provide any implementation
+ for this callback so this call is a no-op.</li>
+
+ <li><code>doc_p.parse("people.xml")</code> is called from
+ <code>main()</code>. The parser opens the file and starts
+ parsing its content.</li>
+
+ <li>The parser encounters the root element. <code>doc_p</code>
+ verifies that the root element is correct and calls
+ <code>_pre()</code> on <code>people_p</code> which is also
+ a no-op. Parsing is now delegated to <code>people_p</code>.</li>
+
+ <li>The parser encounters the <code>person</code> element.
+ <code>people_p</code> determines that <code>person_p</code>
+ is responsible for parsing this element. <code>pre()</code>
+ and <code>_pre()</code> callbacks are called on <code>person_p</code>.
+ Parsing is now delegated to <code>person_p</code>.</li>
+
+ <li>The parser encounters the <code>first-name</code> element.
+ <code>person_p</code> determines that <code>string_p</code>
+ is responsible for parsing this element. <code>pre()</code>
+ and <code>_pre()</code> callbacks are called on <code>string_p</code>.
+ Parsing is now delegated to <code>string_p</code>.</li>
+
+ <li>The parser encounters character content consisting of
+ <code>"John"</code>. The <code>_characters()</code> callback is
+ called on <code>string_p</code>.</li>
+
+ <li>The parser encounters the end of <code>first-name</code>
+ element. The <code>_post()</code> and <code>post_string()</code>
+ callbacks are called on <code>string_p</code>. The
+ <code>first_name()</code> callback is called on <code>person_p</code>
+ with the return value of <code>post_string()</code>. The
+ <code>first_name()</code> implementation prints
+ <code>"first: John"</code> to <code>cout</code>.
+ Parsing is now returned to <code>person_p</code>.</li>
+
+ <li>Steps analogous to 5-7 are performed for the <code>last-name</code>,
+ <code>gender</code>, and <code>age</code> elements.</li>
+
+ <li>The parser encounters the end of <code>person</code>
+ element. The <code>_post()</code> and <code>post_person()</code>
+ callbacks are called on <code>person_p</code>. The
+ <code>person()</code> callback is called on <code>people_p</code>.
+ The <code>person()</code> implementation prints a new line
+ to <code>cout</code>. Parsing is now returned to
+ <code>people_p</code>.</li>
+
+ <li>Steps 4-9 are performed for the second <code>person</code>
+ element.</li>
+
+ <li>The parser encounters the end of <code>people</code>
+ element. The <code>_post()</code> callback is called on
+ <code>people_p</code>. The <code>doc_p.parse("people.xml")</code>
+ call returns to <code>main()</code>.</li>
+
+ <li><code>people_p.post_people()</code> is called from
+ <code>main()</code> which is a no-op.</li>
+
+ </ol>
+
+
+ <!-- Chpater 4 -->
+
+
+ <h1><a name="4">4 Type Maps</a></h1>
+
+ <p>There are many useful things you can do inside parser callbacks as they
+ are right now. There are, however, times when you want to propagate
+ some information from one parser to another or to the caller of the
+ parser. One common task that would greatly benefit from such a
+ possibility is building a tree-like in-memory object model of the
+ data stored in XML. During execution, each individual sub-parser
+ would create a sub-tree and return it to its <em>parent</em> parser
+ which can then incorporate this sub-tree into the whole tree.</p>
+
+ <p>In this chapter we will discuss the mechanisms offered by the
+ C++/Parser mapping for returning information from individual
+ parsers and see how to use them to build an object model
+ of our people vocabulary.</p>
+
+ <h2><a name="4.1">4.1 Object Model</a></h2>
+
+ <p>An object model for our person record example could
+ look like this (saved in the <code>people.hxx</code> file):</p>
+
+ <pre class="c++">
+#include &lt;string>
+#include &lt;vector>
+
+enum gender
+{
+ male,
+ female
+};
+
+class person
+{
+public:
+ person (const std::string&amp; first,
+ const std::string&amp; last,
+ ::gender gender,
+ short age)
+ : first_ (first), last_ (last),
+ gender_ (gender), age_ (age)
+ {
+ }
+
+ const std::string&amp;
+ first () const
+ {
+ return first_;
+ }
+
+ const std::string&amp;
+ last () const
+ {
+ return last_;
+ }
+
+ ::gender
+ gender () const
+ {
+ return gender_;
+ }
+
+ short
+ age () const
+ {
+ return age_;
+ }
+
+private:
+ std::string first_;
+ std::string last_;
+ ::gender gender_;
+ short age_;
+};
+
+typedef std::vector&lt;person> people;
+ </pre>
+
+ <p>While it is clear which parser is responsible for which part of
+ the object model, it is not exactly clear how, for
+ example, <code>gender_pimpl</code> will deliver <code>gender</code>
+ to <code>person_pimpl</code>. You might have noticed that
+ <code>string_pimpl</code> manages to deliver its value to the
+ <code>first_name()</code> callback of <code>person_pimpl</code>. Let's
+ see how we can utilize the same mechanism to propagate our
+ own data.</p>
+
+ <p>There is a way to tell the XSD compiler that you want to
+ exchange data between parsers. More precisely, for each
+ type defined in XML Schema, you can tell the compiler two things.
+ First, the return type of the <code>post_*()</code> callback
+ in the parser skeleton generated for this type. And, second,
+ the argument type for callbacks corresponding to elements and
+ attributes of this type. For example, for XML Schema type
+ <code>gender</code> we can specify the return type for
+ <code>post_gender()</code> in the <code>gender_pskel</code>
+ skeleton and the argument type for the <code>gender()</code> callback
+ in the <code>person_pskel</code> skeleton. As you might have guessed,
+ the generated code will then pass the return value from the
+ <code>post_*()</code> callback as an argument to the element or
+ attribute callback.</p>
+
+ <p>The way to tell the XSD compiler about these XML Schema to
+ C++ mappings is with type map files. Here is a simple type
+ map for the <code>gender</code> type from the previous paragraph:</p>
+
+ <pre class="type-map">
+include "people.hxx";
+gender ::gender ::gender;
+ </pre>
+
+ <p>The first line indicates that the generated code must include
+ <code>people.hxx</code> in order to get the definition for the
+ <code>gender</code> type. The second line specifies that both
+ argument and return types for the <code>gender</code>
+ XML Schema type should be the <code>::gender</code> C++ enum
+ (we use fully-qualified C++ names to avoid name clashes).
+ The next section will describe the type map format in detail.
+ We save this type map in <code>people.map</code> and
+ then translate our schemas with the <code>--type-map</code>
+ option to let the XSD compiler know about our type map:</p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --type-map people.map people.xsd
+ </pre>
+
+ <p>If we now look at the generated <code>people-pskel.hxx</code>,
+ we will see the following changes in the <code>gender_pskel</code> and
+ <code>person_pskel</code> skeletons:</p>
+
+ <pre class="c++">
+#include "people.hxx"
+
+class gender_pskel: public virtual xml_schema::string_pskel
+{
+ virtual ::gender
+ post_gender () = 0;
+
+ ...
+};
+
+class person_pskel: public xml_schema::complex_content
+{
+ virtual void
+ gender (::gender);
+
+ ...
+};
+ </pre>
+
+ <p>Notice that <code>#include "people.hxx"</code> was added to
+ the generated header file from the type map to provide the
+ definition for the <code>gender</code> enum.</p>
+
+ <h2><a name="4.2">4.2 Type Map File Format</a></h2>
+
+ <p>Type map files are used to define a mapping between XML Schema
+ and C++ types. The compiler uses this information
+ to determine return types of <code>post_*()</code>
+ callbacks in parser skeletons corresponding to XML Schema
+ types as well as argument types for callbacks corresponding
+ to elements and attributes of these types.</p>
+
+ <p>The compiler has a set of predefined mapping rules that map
+ the built-in XML Schema types to suitable C++ types (discussed
+ below) and all other types to <code>void</code>.
+ By providing your own type maps you can override these predefined
+ rules. The format of the type map file is presented below:
+ </p>
+
+ <pre class="type-map">
+namespace &lt;schema-namespace> [&lt;cxx-namespace>]
+{
+ (include &lt;file-name>;)*
+ ([type] &lt;schema-type> &lt;cxx-ret-type> [&lt;cxx-arg-type>];)*
+}
+ </pre>
+
+ <p>Both <code><i>&lt;schema-namespace></i></code> and
+ <code><i>&lt;schema-type></i></code> are regex patterns while
+ <code><i>&lt;cxx-namespace></i></code>,
+ <code><i>&lt;cxx-ret-type></i></code>, and
+ <code><i>&lt;cxx-arg-type></i></code> are regex pattern
+ substitutions. All names can be optionally enclosed in
+ <code>" "</code>, for example, to include white-spaces.</p>
+
+ <p><code><i>&lt;schema-namespace></i></code> determines XML
+ Schema namespace. Optional <code><i>&lt;cxx-namespace></i></code>
+ is prefixed to every C++ type name in this namespace declaration.
+ <code><i>&lt;cxx-ret-type></i></code> is a C++ type name that is
+ used as a return type for the <code>post_*()</code> callback.
+ Optional <code><i>&lt;cxx-arg-type></i></code> is an argument
+ type for callbacks corresponding to elements and attributes
+ of this type. If <code><i>&lt;cxx-arg-type></i></code> is not
+ specified, it defaults to <code><i>&lt;cxx-ret-type></i></code>
+ if <code><i>&lt;cxx-ret-type></i></code> ends with <code>*</code> or
+ <code>&amp;</code> (that is, it is a pointer or a reference) and
+ <code>const&nbsp;<i>&lt;cxx-ret-type></i>&amp;</code>
+ otherwise.
+ <code><i>&lt;file-name></i></code> is a file name either in the
+ <code>" "</code> or <code>&lt; ></code> format
+ and is added with the <code>#include</code> directive to
+ the generated code.</p>
+
+ <p>The <code><b>#</b></code> character starts a comment that ends
+ with a new line or end of file. To specify a name that contains
+ <code><b>#</b></code> enclose it in <code><b>" "</b></code>.
+ For example:</p>
+
+ <pre>
+namespace http://www.example.com/xmlns/my my
+{
+ include "my.hxx";
+
+ # Pass apples by value.
+ #
+ apple apple;
+
+ # Pass oranges as pointers.
+ #
+ orange orange_t*;
+}
+ </pre>
+
+ <p>In the example above, for the
+ <code>http://www.example.com/xmlns/my#orange</code>
+ XML Schema type, the <code>my::orange_t*</code> C++ type will
+ be used as both return and argument types.</p>
+
+ <p>Several namespace declarations can be specified in a single
+ file. The namespace declaration can also be completely
+ omitted to map types in a schema without a namespace. For
+ instance:</p>
+
+ <pre class="type-map">
+include "my.hxx";
+apple apple;
+
+namespace http://www.example.com/xmlns/my
+{
+ orange "const orange_t*";
+}
+ </pre>
+
+ <p>The compiler has a number of predefined mapping rules for
+ the built-in XML Schema types which can be presented as the
+ following map files. The string-based XML Schema types are
+ mapped to either <code>std::string</code> or
+ <code>std::wstring</code> depending on the character type
+ selected (see <a href="#5.2"> Section 5.2, "Character Type and
+ Encoding"</a> for more information). The binary XML Schema
+ types are mapped to either <code>std::unique_ptr&lt;xml_schema::buffer></code>
+ or <code>std::auto_ptr&lt;xml_schema::buffer></code>
+ depending on the C++ standard selected (C++11 or C++98,
+ respectively; refer to the <code>--std</code> XSD compiler
+ command line option for details).</p>
+
+ <pre class="type-map">
+namespace http://www.w3.org/2001/XMLSchema
+{
+ boolean bool bool;
+
+ byte "signed char" "signed char";
+ unsignedByte "unsigned char" "unsigned char";
+
+ short short short;
+ unsignedShort "unsigned short" "unsigned short";
+
+ int int int;
+ unsignedInt "unsigned int" "unsigned int";
+
+ long "long long" "long long";
+ unsignedLong "unsigned long long" "unsigned long long";
+
+ integer "long long" "long long";
+
+ negativeInteger "long long" "long long";
+ nonPositiveInteger "long long" "long long";
+
+ positiveInteger "unsigned long long" "unsigned long long";
+ nonNegativeInteger "unsigned long long" "unsigned long long";
+
+ float float float;
+ double double double;
+ decimal double double;
+
+ string std::string;
+ normalizedString std::string;
+ token std::string;
+ Name std::string;
+ NMTOKEN std::string;
+ NCName std::string;
+ ID std::string;
+ IDREF std::string;
+ language std::string;
+ anyURI std::string;
+
+ NMTOKENS xml_schema::string_sequence;
+ IDREFS xml_schema::string_sequence;
+
+ QName xml_schema::qname;
+
+ base64Binary std::[unique|auto]_ptr&lt;xml_schema::buffer>
+ std::[unique|auto]_ptr&lt;xml_schema::buffer>;
+ hexBinary std::[unique|auto]_ptr&lt;xml_schema::buffer>
+ std::[unique|auto]_ptr&lt;xml_schema::buffer>;
+
+ date xml_schema::date;
+ dateTime xml_schema::date_time;
+ duration xml_schema::duration;
+ gDay xml_schema::gday;
+ gMonth xml_schema::gmonth;
+ gMonthDay xml_schema::gmonth_day;
+ gYear xml_schema::gyear;
+ gYearMonth xml_schema::gyear_month;
+ time xml_schema::time;
+}
+ </pre>
+
+ <p>For more information about the mapping of the built-in XML Schema types
+ to C++ types refer to <a href="#6">Chapter 6, "Built-In XML Schema Type
+ Parsers"</a>. The last predefined rule maps anything that wasn't
+ mapped by previous rules to <code>void</code>:</p>
+
+ <pre class="type-map">
+namespace .*
+{
+ .* void void;
+}
+ </pre>
+
+
+ <p>When you provide your own type maps with the
+ <code>--type-map</code> option, they are evaluated first. This
+ allows you to selectively override any of the predefined rules.
+ Note also that if you change the mapping
+ of a built-in XML Schema type then it becomes your responsibility
+ to provide the corresponding parser skeleton and implementation
+ in the <code>xml_schema</code> namespace. You can include the
+ custom definitions into the generated header file using the
+ <code>--hxx-prologue-*</code> options.</p>
+
+ <h2><a name="4.3">4.3 Parser Implementations</a></h2>
+
+ <p>With the knowledge from the previous section, we can proceed
+ with creating a type map that maps types in the <code>people.xsd</code>
+ schema to our object model classes in
+ <code>people.hxx</code>. In fact, we already have the beginning
+ of our type map file in <code>people.map</code>. Let's extend
+ it with the rest of the types:</p>
+
+ <pre class="type-map">
+include "people.hxx";
+
+gender ::gender ::gender;
+person ::person;
+people ::people;
+ </pre>
+
+ <p>There are a few things to note about this type map. We did not
+ provide the argument types for <code>person</code> and
+ <code>people</code> because the default constant reference is
+ exactly what we need. We also did not provide any mappings
+ for built-in XML Schema types <code>string</code> and
+ <code>short</code> because they are handled by the predefined
+ rules and we are happy with the result. Note also that
+ all C++ types are fully qualified. This is done to avoid
+ potential name conflicts in the generated code. Now we can
+ recompile our schema and move on to implementing the parsers:</p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --xml-parser expat --type-map people.map people.xsd
+ </pre>
+
+ <p>Here is the implementation of our three parsers in full. One
+ way to save typing when implementing your own parsers is
+ to open the generated code and copy the signatures of parser
+ callbacks into your code. Or you could always auto generate the
+ sample implementations and fill them with your code.</p>
+
+
+ <pre class="c++">
+#include "people-pskel.hxx"
+
+class gender_pimpl: public gender_pskel,
+ public xml_schema::string_pimpl
+{
+public:
+ virtual ::gender
+ post_gender ()
+ {
+ return post_string () == "male" ? male : female;
+ }
+};
+
+class person_pimpl: public person_pskel
+{
+public:
+ virtual void
+ first_name (const std::string&amp; f)
+ {
+ first_ = f;
+ }
+
+ virtual void
+ last_name (const std::string&amp; l)
+ {
+ last_ = l;
+ }
+
+ virtual void
+ gender (::gender g)
+ {
+ gender_ = g;
+ }
+
+ virtual void
+ age (short a)
+ {
+ age_ = a;
+ }
+
+ virtual ::person
+ post_person ()
+ {
+ return ::person (first_, last_, gender_, age_);
+ }
+
+private:
+ std::string first_;
+ std::string last_;
+ ::gender gender_;
+ short age_;
+};
+
+class people_pimpl: public people_pskel
+{
+public:
+ virtual void
+ person (const ::person&amp; p)
+ {
+ people_.push_back (p);
+ }
+
+ virtual ::people
+ post_people ()
+ {
+ ::people r;
+ r.swap (people_);
+ return r;
+ }
+
+private:
+ ::people people_;
+};
+ </pre>
+
+ <p>This code fragment should look familiar by now. Just note that
+ all the <code>post_*()</code> callbacks now have return types instead
+ of <code>void</code>. Here is the implementation of the test
+ driver for this example:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ // Construct the parser.
+ //
+ xml_schema::short_pimpl short_p;
+ xml_schema::string_pimpl string_p;
+
+ gender_pimpl gender_p;
+ person_pimpl person_p;
+ people_pimpl people_p;
+
+ person_p.parsers (string_p, string_p, gender_p, short_p);
+ people_p.parsers (person_p);
+
+ // Parse the document to obtain the object model.
+ //
+ xml_schema::document doc_p (people_p, "people");
+
+ people_p.pre ();
+ doc_p.parse (argv[1]);
+ people ppl = people_p.post_people ();
+
+ // Print the object model.
+ //
+ for (people::iterator i (ppl.begin ()); i != ppl.end (); ++i)
+ {
+ cout &lt;&lt; "first: " &lt;&lt; i->first () &lt;&lt; endl
+ &lt;&lt; "last: " &lt;&lt; i->last () &lt;&lt; endl
+ &lt;&lt; "gender: " &lt;&lt; (i->gender () == male ? "male" : "female") &lt;&lt; endl
+ &lt;&lt; "age: " &lt;&lt; i->age () &lt;&lt; endl
+ &lt;&lt; endl;
+ }
+}
+ </pre>
+
+ <p>The parser creation and assembly part is exactly the same as in
+ the previous chapter. The parsing part is a bit different:
+ <code>post_people()</code> now has a return value which is the
+ complete object model. We store it in the
+ <code>ppl</code> variable. The last bit of the code simply iterates
+ over the <code>people</code> vector and prints the information
+ for each person. We save the last two code fragments to
+ <code>driver.cxx</code> and proceed to compile and test
+ our new application:</p>
+
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx people-pskel.cxx
+$ c++ -std=c++11 -o driver driver.o people-pskel.o -lexpat
+$ ./driver people.xml
+first: John
+last: Doe
+gender: male
+age: 32
+
+first: Jane
+last: Doe
+gender: female
+age: 28
+ </pre>
+
+
+ <!-- Mapping Configuration -->
+
+
+ <h1><a name="5">5 Mapping Configuration</a></h1>
+
+ <p>The C++/Parser mapping has a number of configuration parameters that
+ determine the overall properties and behavior of the generated code.
+ Configuration parameters are specified with the XSD command line
+ options and include the C++ standard, the character type that is used
+ by the generated code, the underlying XML parser, whether the XML Schema
+ validation is performed in the generated code, and support for XML Schema
+ polymorphism. This chapter describes these configuration
+ parameters in more detail. For more ways to configure the generated
+ code refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>.
+ </p>
+
+ <h2><a name="5.1">5.1 C++ Standard</a></h2>
+
+ <p>The C++/Parser mapping provides support for ISO/IEC C++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</p>
+
+ <h2><a name="5.2">5.2 Character Type and Encoding</a></h2>
+
+ <p>The C++/Parser mapping has built-in support for two character types:
+ <code>char</code> and <code>wchar_t</code>. You can select the
+ character type with the <code>--char-type</code> command line
+ option. The default character type is <code>char</code>. The
+ string-based built-in XML Schema types are returned as either
+ <code>std::string</code> or <code>std::wstring</code> depending
+ on the character type selected.</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. You can select which encoding should be used
+ in the object model 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>
+
+ <p>Note also that the character encoding that is used in the object model
+ is independent of the encodings used in input and output XML. In fact,
+ all three (object mode, input XML, and output XML) can have different
+ encodings.</p>
+
+ <h2><a name="5.3">5.3 Underlying XML Parser</a></h2>
+
+ <p>The C++/Parser mapping can be used with either Xerces-C++ or Expat
+ as the underlying XML parser. You can select the XML parser with
+ the <code>--xml-parser</code> command line option. Valid values
+ for this option are <code>xerces</code> and <code>expat</code>.
+ The default XML parser is Xerces-C++.</p>
+
+ <p>The generated code is identical for both parsers except for the
+ <code>xml_schema::document</code> class in which some of the
+ <code>parse()</code> functions are parser-specific as described
+ in <a href="#7">Chapter 7, "Document Parser and Error Handling"</a>.</p>
+
+
+ <h2><a name="5.4">5.4 XML Schema Validation</a></h2>
+
+ <p>The C++/Parser mapping provides support for validating a
+ commonly-used subset of W3C XML Schema in the generated code.
+ For the list of supported XML Schema constructs refer to
+ <a href="#A">Appendix A, "Supported XML Schema Constructs"</a>.</p>
+
+ <p>By default validation in the generated code is disabled if
+ the underlying XML parser is validating (Xerces-C++) and
+ enabled otherwise (Expat). See <a href="#5.3">Section 5.3,
+ "Underlying XML Parser"</a> for more information about
+ the underlying XML parser. You can override the default
+ behavior with the <code>--generate-validation</code>
+ and <code>--suppress-validation</code> command line options.</p>
+
+
+ <h2><a name="5.5">5.5 Support for Polymorphism</a></h2>
+
+ <p>By default the XSD compiler generates non-polymorphic code. If your
+ vocabulary uses XML Schema polymorphism in the form of <code>xsi:type</code>
+ and/or substitution groups, then you will need to compile your schemas
+ with the <code>--generate-polymorphic</code> option to produce
+ polymorphism-aware code as well as pass <code>true</code> as the last
+ argument to the <code>xml_schema::document</code>'s constructors.</p>
+
+ <p>When using the polymorphism-aware generated code, you can specify
+ several parsers for a single element by passing a parser map
+ instead of an individual parser to the parser connection function
+ for the element. One of the parsers will then be looked up and used
+ depending on the <code>xsi:type</code> attribute value or an element
+ name from a substitution group. Consider the following schema as an
+ example:</p>
+
+ <pre class="xml">
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="person">
+ &lt;xs:sequence>
+ &lt;xs:element name="name" type="xs:string"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;!-- substitution group root -->
+ &lt;xs:element name="person" type="person"/>
+
+ &lt;xs:complexType name="superman">
+ &lt;xs:complexContent>
+ &lt;xs:extension base="person">
+ &lt;xs:attribute name="can-fly" type="xs:boolean"/>
+ &lt;/xs:extension>
+ &lt;/xs:complexContent>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="superman"
+ type="superman"
+ substitutionGroup="person"/>
+
+ &lt;xs:complexType name="batman">
+ &lt;xs:complexContent>
+ &lt;xs:extension base="superman">
+ &lt;xs:attribute name="wing-span" type="xs:unsignedInt"/>
+ &lt;/xs:extension>
+ &lt;/xs:complexContent>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="batman"
+ type="batman"
+ substitutionGroup="superman"/>
+
+ &lt;xs:complexType name="supermen">
+ &lt;xs:sequence>
+ &lt;xs:element ref="person" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="supermen" type="supermen"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Conforming XML documents can use the <code>superman</code>
+ and <code>batman</code> types in place of the <code>person</code>
+ type either by specifying the type with the <code>xsi:type</code>
+ attributes or by using the elements from the substitution
+ group, for instance:</p>
+
+
+ <pre class="xml">
+&lt;supermen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+ &lt;person>
+ &lt;name>John Doe&lt;/name>
+ &lt;/person>
+
+ &lt;superman can-fly="false">
+ &lt;name>James "007" Bond&lt;/name>
+ &lt;/superman>
+
+ &lt;superman can-fly="true" wing-span="10" xsi:type="batman">
+ &lt;name>Bruce Wayne&lt;/name>
+ &lt;/superman>
+
+&lt;/supermen>
+ </pre>
+
+ <p>To print the data stored in such XML documents we can implement
+ the parsers as follows:</p>
+
+ <pre class="c++">
+class person_pimpl: public virtual person_pskel
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse person" &lt;&lt; endl;
+ }
+
+ virtual void
+ name (const std::string&amp; v)
+ {
+ cout &lt;&lt; "name: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_person ()
+ {
+ cout &lt;&lt; "finished parsing person" &lt;&lt; endl;
+ }
+};
+
+class superman_pimpl: public virtual superman_pskel,
+ public person_pimpl
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse superman" &lt;&lt; endl;
+ }
+
+ virtual void
+ can_fly (bool v)
+ {
+ cout &lt;&lt; "can-fly: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_person ()
+ {
+ post_superman ();
+ }
+
+ virtual void
+ post_superman ()
+ {
+ cout &lt;&lt; "finished parsing superman" &lt;&lt; endl
+ }
+};
+
+class batman_pimpl: public virtual batman_pskel,
+ public superman_pimpl
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse batman" &lt;&lt; endl;
+ }
+
+ virtual void
+ wing_span (unsigned int v)
+ {
+ cout &lt;&lt; "wing-span: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_superman ()
+ {
+ post_batman ();
+ }
+
+ virtual void
+ post_batman ()
+ {
+ cout &lt;&lt; "finished parsing batman" &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Note that because the derived type parsers (<code>superman_pskel</code>
+ and <code>batman_pskel</code>) are called via the <code>person_pskel</code>
+ interface, we have to override the <code>post_person()</code>
+ virtual function in <code>superman_pimpl</code> to call
+ <code>post_superman()</code> and the <code>post_superman()</code>
+ virtual function in <code>batman_pimpl</code> to call
+ <code>post_batman()</code>.</p>
+
+ <p>The following code fragment shows how to connect the parsers together.
+ Notice that for the <code>person</code> element in the <code>supermen_p</code>
+ parser we specify a parser map instead of a specific parser and we pass
+ <code>true</code> as the last argument to the document parser constructor
+ to indicate that we are parsing potentially-polymorphic XML documents:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ // Construct the parser.
+ //
+ xml_schema::string_pimpl string_p;
+ xml_schema::boolean_pimpl boolean_p;
+ xml_schema::unsigned_int_pimpl unsigned_int_p;
+
+ person_pimpl person_p;
+ superman_pimpl superman_p;
+ batman_pimpl batman_p;
+
+ xml_schema::parser_map_impl person_map;
+ supermen_pimpl supermen_p;
+
+ person_p.parsers (string_p);
+ superman_p.parsers (string_p, boolean_p);
+ batman_p.parsers (string_p, boolean_p, unsigned_int_p);
+
+ // Here we are specifying a parser map which containes several
+ // parsers that can be used to parse the person element.
+ //
+ person_map.insert (person_p);
+ person_map.insert (superman_p);
+ person_map.insert (batman_p);
+
+ supermen_p.person_parser (person_map);
+
+ // Parse the XML document. The last argument to the document's
+ // constructor indicates that we are parsing polymorphic XML
+ // documents.
+ //
+ xml_schema::document doc_p (supermen_p, "supermen", true);
+
+ supermen_p.pre ();
+ doc_p.parse (argv[1]);
+ supermen_p.post_supermen ();
+}
+ </pre>
+
+ <p>When polymorphism-aware code is generated, each element's
+ <code>*_parser()</code> function is overloaded to also accept
+ an object of the <code>xml_schema::parser_map</code> type.
+ For example, the <code>supermen_pskel</code> class from the
+ above example looks like this:</p>
+
+ <pre class="c++">
+class supermen_pskel: public xml_schema::parser_complex_content
+{
+public:
+
+ ...
+
+ // Parser construction API.
+ //
+ void
+ parsers (person_pskel&amp;);
+
+ // Individual element parsers.
+ //
+ void
+ person_parser (person_pskel&amp;);
+
+ void
+ person_parser (const xml_schema::parser_map&amp;);
+
+ ...
+};
+ </pre>
+
+ <p>Note that you can specify both the individual (static) parser and
+ the parser map. The individual parser will be used when the static
+ element type and the dynamic type of the object being parsed are
+ the same. This is the case, for example, when there is no
+ <code>xsi:type</code> attribute and the element hasn't been
+ substituted. Because the individual parser for an element is
+ cached and no map lookup is necessary, it makes sense to specify
+ both the individual parser and the parser map when most of the
+ objects being parsed are of the static type and optimal
+ performance is important. The following code fragment shows
+ how to change the above example to set both the individual
+ parser and the parser map:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ ...
+
+ person_map.insert (superman_p);
+ person_map.insert (batman_p);
+
+ supermen_p.person_parser (person_p);
+ supermen_p.person_parser (person_map);
+
+ ...
+}
+ </pre>
+
+
+ <p>The <code>xml_schema::parser_map</code> interface and the
+ <code>xml_schema::parser_map_impl</code> default implementation
+ are presented below:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_map
+ {
+ public:
+ virtual parser_base*
+ find (const ro_string* type) const = 0;
+ };
+
+ class parser_map_impl: public parser_map
+ {
+ public:
+ void
+ insert (parser_base&amp;);
+
+ virtual parser_base*
+ find (const ro_string* type) const;
+
+ private:
+ parser_map_impl (const parser_map_impl&amp;);
+
+ parser_map_impl&amp;
+ operator= (const parser_map_impl&amp;);
+
+ ...
+ };
+}
+ </pre>
+
+ <p>The <code>type</code> argument in the <code>find()</code> virtual
+ function is the type name and namespace from the xsi:type attribute
+ (the namespace prefix is resolved to the actual XML namespace)
+ or the type of an element from the substitution group in the form
+ <code>"&lt;name>&nbsp;&lt;namespace>"</code> with the space and the
+ namespace part absent if the type does not have a namespace.
+ You can obtain a parser's dynamic type in the same format
+ using the <code>_dynamic_type()</code> function. The static
+ type can be obtained by calling the static <code>_static_type()</code>
+ function, for example <code>person_pskel::_static_type()</code>.
+ Both functions return a C string (<code>const char*</code> or
+ <code>const wchar_t*</code>, depending on the character type
+ used) which is valid for as long as the application is running.
+ The following example shows how we can implement our own parser
+ map using <code>std::map</code>:</p>
+
+
+ <pre class="c++">
+#include &lt;map>
+#include &lt;string>
+
+class parser_map: public xml_schema::parser_map
+{
+public:
+ void
+ insert (xml_schema::parser_base&amp; p)
+ {
+ map_[p._dynamic_type ()] = &amp;p;
+ }
+
+ virtual xml_schema::parser_base*
+ find (const xml_schema::ro_string* type) const
+ {
+ map::const_iterator i = map_.find (type);
+ return i != map_.end () ? i->second : 0;
+ }
+
+private:
+ typedef std::map&lt;std::string, xml_schema::parser_base*> map;
+ map map_;
+};
+ </pre>
+
+ <p>Most of code presented in this section is taken from the
+ <code>polymorphism</code> example which can be found in the
+ <code>cxx/parser/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.
+ Handling of <code>xsi:type</code> and substitution groups when used on
+ root elements requires a number of special actions as shown in
+ the <code>polyroot</code> example.</p>
+
+
+ <!-- Built-in XML Schema Type Parsers -->
+
+
+ <h1><a name="6">6 Built-In XML Schema Type Parsers</a></h1>
+
+ <p>The XSD runtime provides parser implementations for all built-in
+ XML Schema types as summarized in the following table. Declarations
+ for these types are automatically included into each generated
+ header file. As a result you don't need to include any headers
+ to gain access to these parser implementations. Note that some
+ parsers return either <code>std::string</code> or
+ <code>std::wstring</code> depending on the character type selected.</p>
+
+ <!-- border="1" is necessary for html2ps -->
+ <table id="builtin" border="1">
+ <tr>
+ <th>XML Schema type</th>
+ <th>Parser implementation in the <code>xml_schema</code> namespace</th>
+ <th>Parser return type</th>
+ </tr>
+
+ <tr>
+ <th colspan="3">anyType and anySimpleType types</th>
+ </tr>
+ <tr>
+ <td><code>anyType</code></td>
+ <td><code>any_type_pimpl</code></td>
+ <td><code>void</code></td>
+ </tr>
+ <tr>
+ <td><code>anySimpleType</code></td>
+ <td><code>any_simple_type_pimpl</code></td>
+ <td><code>void</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">fixed-length integral types</th>
+ </tr>
+ <!-- 8-bit -->
+ <tr>
+ <td><code>byte</code></td>
+ <td><code>byte_pimpl</code></td>
+ <td><code>signed&nbsp;char</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedByte</code></td>
+ <td><code>unsigned_byte_pimpl</code></td>
+ <td><code>unsigned&nbsp;char</code></td>
+ </tr>
+
+ <!-- 16-bit -->
+ <tr>
+ <td><code>short</code></td>
+ <td><code>short_pimpl</code></td>
+ <td><code>short</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedShort</code></td>
+ <td><code>unsigned_short_pimpl</code></td>
+ <td><code>unsigned&nbsp;short</code></td>
+ </tr>
+
+ <!-- 32-bit -->
+ <tr>
+ <td><code>int</code></td>
+ <td><code>int_pimpl</code></td>
+ <td><code>int</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedInt</code></td>
+ <td><code>unsigned_int_pimpl</code></td>
+ <td><code>unsigned&nbsp;int</code></td>
+ </tr>
+
+ <!-- 64-bit -->
+ <tr>
+ <td><code>long</code></td>
+ <td><code>long_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedLong</code></td>
+ <td><code>unsigned_long_pimpl</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_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>nonPositiveInteger</code></td>
+ <td><code>non_positive_integer_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>nonNegativeInteger</code></td>
+ <td><code>non_negative_integer_pimpl</code></td>
+ <td><code>unsigned long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>positiveInteger</code></td>
+ <td><code>positive_integer_pimpl</code></td>
+ <td><code>unsigned long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>negativeInteger</code></td>
+ <td><code>negative_integer_pimpl</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_pimpl</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_pimpl</code></td>
+ <td><code>float</code></td>
+ </tr>
+ <tr>
+ <td><code>double</code></td>
+ <td><code>double_pimpl</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_pimpl</code></td>
+ <td><code>double</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">string-based types</th>
+ </tr>
+ <tr>
+ <td><code>string</code></td>
+ <td><code>string_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>normalizedString</code></td>
+ <td><code>normalized_string_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>token</code></td>
+ <td><code>token_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>Name</code></td>
+ <td><code>name_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>NMTOKEN</code></td>
+ <td><code>nmtoken_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>NCName</code></td>
+ <td><code>ncname_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <td><code>language</code></td>
+ <td><code>language_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">qualified name</th>
+ </tr>
+ <tr>
+ <td><code>QName</code></td>
+ <td><code>qname_pimpl</code></td>
+ <td><code>xml_schema::qname</code><br/><a href="#6.1">Section 6.1,
+ "<code>QName</code> Parser"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">ID/IDREF types</th>
+ </tr>
+ <tr>
+ <td><code>ID</code></td>
+ <td><code>id_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>IDREF</code></td>
+ <td><code>idref_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">list types</th>
+ </tr>
+ <tr>
+ <td><code>NMTOKENS</code></td>
+ <td><code>nmtokens_pimpl</code></td>
+ <td><code>xml_schema::string_sequence</code><br/><a href="#6.2">Section
+ 6.2, "<code>NMTOKENS</code> and <code>IDREFS</code> Parsers"</a></td>
+ </tr>
+ <tr>
+ <td><code>IDREFS</code></td>
+ <td><code>idrefs_pimpl</code></td>
+ <td><code>xml_schema::string_sequence</code><br/><a href="#6.2">Section
+ 6.2, "<code>NMTOKENS</code> and <code>IDREFS</code> Parsers"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">URI types</th>
+ </tr>
+ <tr>
+ <td><code>anyURI</code></td>
+ <td><code>uri_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">binary types</th>
+ </tr>
+ <tr>
+ <td><code>base64Binary</code></td>
+ <td><code>base64_binary_pimpl</code></td>
+ <td><code>std::[unique|auto]_ptr&lt; xml_schema::buffer></code><br/>
+ <a href="#6.3">Section 6.3, "<code>base64Binary</code> and
+ <code>hexBinary</code> Parsers"</a></td>
+ </tr>
+ <tr>
+ <td><code>hexBinary</code></td>
+ <td><code>hex_binary_pimpl</code></td>
+ <td><code>std::[unique|auto]_ptr&lt; xml_schema::buffer></code><br/>
+ <a href="#6.3">Section 6.3, "<code>base64Binary</code> and
+ <code>hexBinary</code> Parsers"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">date/time types</th>
+ </tr>
+ <tr>
+ <td><code>date</code></td>
+ <td><code>date_pimpl</code></td>
+ <td><code>xml_schema::date</code><br/><a href="#6.5">Section 6.5,
+ "<code>date</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>dateTime</code></td>
+ <td><code>date_time_pimpl</code></td>
+ <td><code>xml_schema::date_time</code><br/><a href="#6.6">Section 6.6,
+ "<code>dateTime</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>duration</code></td>
+ <td><code>duration_pimpl</code></td>
+ <td><code>xml_schema::duration</code><br/><a href="#6.7">Section 6.7,
+ "<code>duration</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gDay</code></td>
+ <td><code>gday_pimpl</code></td>
+ <td><code>xml_schema::gday</code><br/><a href="#6.8">Section 6.8,
+ "<code>gDay</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gMonth</code></td>
+ <td><code>gmonth_pimpl</code></td>
+ <td><code>xml_schema::gmonth</code><br/><a href="#6.9">Section 6.9,
+ "<code>gMonth</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gMonthDay</code></td>
+ <td><code>gmonth_day_pimpl</code></td>
+ <td><code>xml_schema::gmonth_day</code><br/><a href="#6.10">Section 6.10,
+ "<code>gMonthDay</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gYear</code></td>
+ <td><code>gyear_pimpl</code></td>
+ <td><code>xml_schema::gyear</code><br/><a href="#6.11">Section 6.11,
+ "<code>gYear</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gYearMonth</code></td>
+ <td><code>gyear_month_pimpl</code></td>
+ <td><code>xml_schema::gyear_month</code><br/><a href="#6.12">Section
+ 6.12, "<code>gYearMonth</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>time</code></td>
+ <td><code>time_pimpl</code></td>
+ <td><code>xml_schema::time</code><br/><a href="#6.13">Section 6.13,
+ "<code>time</code> Parser"</a></td>
+ </tr>
+
+ </table>
+
+ <h2><a name="6.1">6.1 <code>QName</code> Parser</a></h2>
+
+ <p>The return type of the <code>qname_pimpl</code> parser implementation
+ is <code>xml_schema::qname</code> which represents an XML qualified
+ name. Its interface is presented below.
+ Note that the <code>std::string</code> type in the interface becomes
+ <code>std::wstring</code> if the selected character type is
+ <code>wchar_t</code>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class qname
+ {
+ public:
+ explicit
+ qname (const std::string&amp; name);
+ qname (const std::string&amp; prefix, const std::string&amp; name);
+
+ const std::string&amp;
+ prefix () const;
+
+ void
+ prefix (const std::string&amp;);
+
+ const std::string&amp;
+ name () const;
+
+ void
+ name (const std::string&amp;);
+ };
+
+ bool
+ operator== (const qname&amp;, const qname&amp;);
+
+ bool
+ operator!= (const qname&amp;, const qname&amp;);
+}
+ </pre>
+
+
+ <h2><a name="6.2">6.2 <code>NMTOKENS</code> and <code>IDREFS</code> Parsers</a></h2>
+
+ <p>The return type of the <code>nmtokens_pimpl</code> and
+ <code>idrefs_pimpl</code> parser implementations is
+ <code>xml_schema::string_sequence</code> which represents a
+ sequence of strings. Its interface is presented below.
+ Note that the <code>std::string</code> type in the interface becomes
+ <code>std::wstring</code> if the selected character type is
+ <code>wchar_t</code>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class string_sequence: public std::vector&lt;std::string>
+ {
+ public:
+ string_sequence ();
+
+ explicit
+ string_sequence (std::vector&lt;std::string>::size_type n,
+ const std::string&amp; x = std::string ());
+
+ template &lt;typename I>
+ string_sequence (const I&amp; begin, const I&amp; end);
+ };
+
+ bool
+ operator== (const string_sequence&amp;, const string_sequence&amp;);
+
+ bool
+ operator!= (const string_sequence&amp;, const string_sequence&amp;);
+}
+ </pre>
+
+
+ <h2><a name="6.3">6.3 <code>base64Binary</code> and <code>hexBinary</code> Parsers</a></h2>
+
+ <p>The return type of the <code>base64_binary_pimpl</code> and
+ <code>hex_binary_pimpl</code> parser implementations is either
+ <code>std::unique_ptr&lt;xml_schema::buffer></code> (C++11) or
+ <code>std::auto_ptr&lt;xml_schema::buffer></code> (C++98),
+ depending on the C++ standard selected (<code>--std</code> XSD
+ compiler option). The <code>xml_schema::buffer</code> type
+ represents a binary buffer and its interface is presented below.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class buffer
+ {
+ public:
+ typedef std::size_t size_t;
+
+ class bounds {}; // Out of bounds exception.
+
+ public:
+ explicit
+ 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 ();
+ };
+
+ bool
+ operator== (const buffer&amp;, const buffer&amp;);
+
+ bool
+ operator!= (const buffer&amp;, const buffer&amp;);
+}
+ </pre>
+
+ <p>If the <code>assume_ownership</code> argument to the constructor
+ is <code>true</code>, the instance assumes the 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>
+
+
+ <h2><a name="6.4">6.4 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++">
+namespace xml_schema
+{
+ 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="6.5">6.5 <code>date</code> Parser</a></h2>
+
+ <p>The return type of the <code>date_pimpl</code> parser implementation
+ is <code>xml_schema::date</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class date
+ {
+ 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);
+
+ 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="6.6">6.6 <code>dateTime</code> Parser</a></h2>
+
+ <p>The return type of the <code>date_time_pimpl</code> parser implementation
+ is <code>xml_schema::date_time</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class date_time
+ {
+ 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);
+
+ 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="6.7">6.7 <code>duration</code> Parser</a></h2>
+
+ <p>The return type of the <code>duration_pimpl</code> parser implementation
+ is <code>xml_schema::duration</code> 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++">
+namespace xml_schema
+{
+ class duration
+ {
+ public:
+ duration (bool negative,
+ unsigned int years, unsigned int months, unsigned int days,
+ unsigned int hours, unsigned int minutes, double seconds);
+
+ 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="6.8">6.8 <code>gDay</code> Parser</a></h2>
+
+ <p>The return type of the <code>gday_pimpl</code> parser implementation
+ is <code>xml_schema::gday</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gday
+ {
+ public:
+ explicit
+ gday (unsigned short day);
+ gday (unsigned short day, short zone_hours, short zone_minutes);
+
+ 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="6.9">6.9 <code>gMonth</code> Parser</a></h2>
+
+ <p>The return type of the <code>gmonth_pimpl</code> parser implementation
+ is <code>xml_schema::gmonth</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gmonth
+ {
+ public:
+ explicit
+ gmonth (unsigned short month);
+ gmonth (unsigned short month, short zone_hours, short zone_minutes);
+
+ 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="6.10">6.10 <code>gMonthDay</code> Parser</a></h2>
+
+ <p>The return type of the <code>gmonth_day_pimpl</code> parser implementation
+ is <code>xml_schema::gmonth_day</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gmonth_day
+ {
+ public:
+ gmonth_day (unsigned short month, unsigned short day);
+ gmonth_day (unsigned short month, unsigned short day,
+ short zone_hours, short zone_minutes);
+
+ 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="6.11">6.11 <code>gYear</code> Parser</a></h2>
+
+ <p>The return type of the <code>gyear_pimpl</code> parser implementation
+ is <code>xml_schema::gyear</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gyear
+ {
+ public:
+ explicit
+ gyear (int year);
+ gyear (int year, short zone_hours, short zone_minutes);
+
+ 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="6.12">6.12 <code>gYearMonth</code> Parser</a></h2>
+
+ <p>The return type of the <code>gyear_month_pimpl</code> parser implementation
+ is <code>xml_schema::gyear_month</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gyear_month
+ {
+ public:
+ gyear_month (int year, unsigned short month);
+ gyear_month (int year, unsigned short month,
+ short zone_hours, short zone_minutes);
+
+ 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="6.13">6.13 <code>time</code> Parser</a></h2>
+
+ <p>The return type of the <code>time_pimpl</code> parser implementation
+ is <code>xml_schema::time</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class time
+ {
+ 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);
+
+ 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>
+
+
+ <!-- Error Handling -->
+
+
+ <h1><a name="7">7 Document Parser and Error Handling</a></h1>
+
+ <p>In this chapter we will discuss the <code>xml_schema::document</code>
+ type as well as the error handling mechanisms provided by the mapping
+ in more detail. As mentioned in <a href="#3.4">Section 3.4,
+ "Connecting the Parsers Together"</a>, the interface of
+ <code>xml_schema::document</code> depends on the underlying XML
+ parser selected (<a href="#5.3">Section 5.3, "Underlying XML
+ Parser"</a>). The following sections describe the
+ <code>document</code> type interface for Xerces-C++ and
+ Expat as underlying parsers.</p>
+
+ <h2><a name="7.1">7.1 Xerces-C++ Document Parser</a></h2>
+
+ <p>When Xerces-C++ is used as the underlying XML parser, the
+ <code>document</code> type has the following interface. Note that
+ if the character type is <code>wchar_t</code>, then the string type
+ in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_base;
+ class error_handler;
+
+ class flags
+ {
+ public:
+ // Do not validate XML documents with the Xerces-C++ validator.
+ //
+ static const unsigned long dont_validate;
+
+ // Do not initialize the Xerces-C++ runtime.
+ //
+ static const unsigned long dont_initialize;
+
+ // Disable handling of subsequent imports for the same namespace
+ // in Xerces-C++ 3.1.0 and later.
+ //
+ static const unsigned long no_multiple_imports;
+ };
+
+ class properties
+ {
+ public:
+ // Add a location for a schema with a target namespace.
+ //
+ void
+ schema_location (const std::string&amp; namespace_,
+ const std::string&amp; location);
+
+ // Add a location for a schema without a target namespace.
+ //
+ void
+ no_namespace_schema_location (const std::string&amp; location);
+ };
+
+ class document
+ {
+ public:
+ document (parser_base&amp; root,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (parser_base&amp; root,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ public:
+ // Parse URI or a local file.
+ //
+ void
+ parse (const std::string&amp; uri,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file with a user-provided error_handler
+ // object.
+ //
+ void
+ parse (const std::string&amp; uri,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file with a user-provided ErrorHandler
+ // object. Note that you must initialize the Xerces-C++ runtime
+ // before calling this function.
+ //
+ void
+ parse (const std::string&amp; uri,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file using a user-provided SAX2XMLReader
+ // object. Note that you must initialize the Xerces-C++ runtime
+ // before calling this function.
+ //
+ void
+ parse (const std::string&amp; uri,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream.
+ //
+ void
+ parse (std::istream&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a user-provided error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a user-provided ErrorHandler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream using a user-provided SAX2XMLReader object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream with a system id.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id and a user-provided
+ // ErrorHandler object. Note that you must initialize the
+ // Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id using a user-provided
+ // SAX2XMLReader object. Note that you must initialize the
+ // Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream with system and public ids.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids and a user-provided
+ // ErrorHandler object. Note that you must initialize the Xerces-C++
+ // runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids using a user-
+ // provided SAX2XMLReader object. Note that you must initialize
+ // the Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse InputSource. Note that you must initialize the Xerces-C++
+ // runtime before calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource with a user-provided error_handler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource with a user-provided ErrorHandler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource using a user-provided SAX2XMLReader object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+ };
+}
+ </pre>
+
+ <p>The <code>document</code> class is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element. The <code>parser_base</code>
+ class is the base type for all parser skeletons. The second and
+ third arguments to the <code>document</code>'s constructors are
+ the root element's name and namespace. The last argument,
+ <code>polymorphic</code>, specifies whether the XML documents
+ being parsed use polymorphism. For more information on support
+ for XML Schema polymorphism in the C++/Parser mapping refer
+ to <a href="#5.5">Section 5.5, "Support for Polymorphism"</a>.</p>
+
+ <p>The rest of the <code>document</code> interface consists of overloaded
+ <code>parse()</code> functions. The last two arguments in each of these
+ functions are <code>flags</code> and <code>properties</code>. The
+ <code>flags</code> argument allows you to modify the default behavior
+ of the parsing functions. The <code>properties</code> argument allows
+ you to override the schema location attributes specified in XML
+ documents. Note that the schema location paths are relative to an
+ XML document unless they are complete URIs. For example if you want
+ to use a local schema file then you will need to use a URI in the
+ form <code>file:///absolute/path/to/your/schema</code>.</p>
+
+ <p>A number of overloaded <code>parse()</code> functions have the
+ <code>system_id</code> and <code>public_id</code> arguments. The
+ system id is a <em>system</em> identifier of the resources being
+ parsed (for example, URI or a full file path). The public id is a
+ <em>public</em> identifier of the resource (for example, an
+ application-specific name or a relative file path). The system id
+ is used to resolve relative paths (for example, schema paths). In
+ diagnostics messages the public id is used if it is available.
+ Otherwise the system id is used.</p>
+
+ <p>The error handling mechanisms employed by the <code>document</code>
+ parser are described in <a href="#7.3">Section 7.3, "Error
+ Handling"</a>.</p>
+
+ <h2><a name="7.2">7.2 Expat Document Parser</a></h2>
+
+ <p>When Expat is used as the underlying XML parser, the
+ <code>document</code> type has the following interface. Note that
+ if the character type is <code>wchar_t</code>, then the string type
+ in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_base;
+ class error_handler;
+
+ class document
+ {
+ public:
+ document (parser_base&amp;,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (parser_base&amp;,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ public:
+ // Parse a local file. The file is accessed with std::ifstream
+ // in binary mode. The std::ios_base::failure exception is used
+ // to report io errors (badbit and failbit).
+ void
+ parse (const std::string&amp; file);
+
+ // Parse a local file with a user-provided error_handler
+ // object. The file is accessed with std::ifstream in binary
+ // mode. The std::ios_base::failure exception is used to report
+ // io errors (badbit and failbit).
+ //
+ void
+ parse (const std::string&amp; file, error_handler&amp;);
+
+ public:
+ // Parse std::istream.
+ //
+ void
+ parse (std::istream&amp;);
+
+ // Parse std::istream with a user-provided error_handler object.
+ //
+ void
+ parse (std::istream&amp;, error_handler&amp;);
+
+ // Parse std::istream with a system id.
+ //
+ void
+ parse (std::istream&amp;, const std::string&amp; system_id);
+
+ // Parse std::istream with a system id and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ error_handler&amp;);
+
+ // Parse std::istream with system and public ids.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id);
+
+ // Parse std::istream with system and public ids and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+
+ public:
+ // Parse a chunk of input. You can call these functions multiple
+ // times with the last call having the last argument true.
+ //
+ void
+ parse (const void* data, std::size_t size, bool last);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ error_handler&amp;);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ error_handler&amp;);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+
+ public:
+ // Low-level Expat-specific parsing API.
+ //
+ void
+ parse_begin (XML_Parser);
+
+ void
+ parse_begin (XML_Parser, const std::string&amp; public_id);
+
+ void
+ parse_begin (XML_Parser, error_handler&amp;);
+
+ void
+ parse_begin (XML_Parser,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+ void
+ parse_end ();
+ };
+}
+ </pre>
+
+ <p>The <code>document</code> class is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element. The <code>parser_base</code>
+ class is the base type for all parser skeletons. The second and
+ third arguments to the <code>document</code>'s constructors are
+ the root element's name and namespace. The last argument,
+ <code>polymorphic</code>, specifies whether the XML documents
+ being parsed use polymorphism. For more information on support
+ for XML Schema polymorphism in the C++/Parser mapping refer
+ to <a href="#5.5">Section 5.5, "Support for Polymorphism"</a>.</p>
+
+ <p>A number of overloaded <code>parse()</code> functions have the
+ <code>system_id</code> and <code>public_id</code> arguments. The
+ system id is a <em>system</em> identifier of the resources being
+ parsed (for example, URI or a full file path). The public id is a
+ <em>public</em> identifier of the resource (for example, an
+ application-specific name or a relative file path). The system id
+ is used to resolve relative paths. In diagnostics messages the
+ public id is used if it is available. Otherwise the system id
+ is used.</p>
+
+ <p>The <code>parse_begin()</code> and <code>parse_end()</code> functions
+ present a low-level, Expat-specific parsing API for maximum control.
+ A typical use-case would look like this (pseudo-code):</p>
+
+ <pre class="c++">
+xxx_pimpl root_p;
+document doc_p (root_p, "root");
+
+root_p.pre ();
+doc_p.parse_begin (xml_parser, "file.xml");
+
+while (more_data_to_parse)
+{
+ // Call XML_Parse or XML_ParseBuffer.
+
+ if (status == XML_STATUS_ERROR)
+ break;
+}
+
+// Call parse_end even in case of an error to translate
+// XML and Schema errors to exceptions or error_handler
+// calls.
+//
+doc.parse_end ();
+result_type result (root_p.post_xxx ());
+ </pre>
+
+ <p>Note that if your vocabulary uses XML namespaces, the
+ <code>XML_ParserCreateNS()</code> functions should be used to create
+ the XML parser. Space (<code>XML_Char (' ')</code>) should be used
+ as a separator (the second argument to <code>XML_ParserCreateNS()</code>).
+ </p>
+
+ <p>The error handling mechanisms employed by the <code>document</code>
+ parser are described in <a href="#7.3">Section 7.3, "Error
+ Handling"</a>.</p>
+
+
+ <h2><a name="7.3">7.3 Error Handling</a></h2>
+
+ <p>There are three categories of errors that can result from running
+ a parser on an XML document: System, XML, and Application.
+ The System category contains memory allocation and file/stream
+ operation errors. The XML category covers XML parsing and
+ well-formedness checking as well as XML Schema validation errors.
+ Finally, the Application category is for application logic errors
+ that you may want to propagate from parser implementations to the
+ caller of the parser.
+ </p>
+
+ <p>The System errors are mapped to the standard exceptions. The
+ out of memory condition is indicated by throwing an instance
+ of <code>std::bad_alloc</code>. The stream operation errors
+ are reported either by throwing an instance of
+ <code>std::ios_base::failure</code> if exceptions are enabled
+ or by setting the stream state.</p>
+
+ <p>Note that if you are parsing <code>std::istream</code> on
+ which exceptions are not enabled, then you will need to
+ check the stream state before calling the <code>post()</code>
+ callback, as shown in the following example:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ ...
+
+ std::ifstream ifs (argv[1]);
+
+ if (ifs.fail ())
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": unable to open" &lt;&lt; endl;
+ return 1;
+ }
+
+ root_p.pre ();
+ doc_p.parse (ifs);
+
+ if (ifs.fail ())
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": io failure" &lt;&lt; endl;
+ return 1;
+ }
+
+ result_type result (root_p.post_xxx ());
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions
+ as shown below:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ ...
+
+ std::ifstream ifs;
+ ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
+ ifs.open (argv[1]);
+
+ root_p.pre ();
+ doc_p.parse (ifs);
+ result_type result (root_p.post_xxx ());
+ }
+ catch (const std::ifstream::failure&amp;)
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": unable to open or io failure" &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+
+ <p>For reporting application errors from parsing callbacks, you
+ can throw any exceptions of your choice. They are propagated to
+ the caller of the parser without any alterations.</p>
+
+ <p>The XML errors can be reported either by throwing the
+ <code>xml_schema::parsing</code> exception or by a callback
+ to the <code>xml_schema::error_handler</code> object (and
+ <code>xercesc::ErrorHandler</code> object in case of Xerces-C++).</p>
+
+ <p>The <code>xml_schema::parsing</code> exception contains
+ a list of warnings and errors that were accumulated during
+ parsing. Note that this exception is thrown only if there
+ was an error. This makes it impossible to obtain warnings
+ from an otherwise successful parsing using this mechanism.
+ The following listing shows the definition of
+ <code>xml_schema::parsing</code> exception. Note that if the
+ character type is <code>wchar_t</code>, then the string type
+ and output stream type in the definition become
+ <code>std::wstring</code> and <code>std::wostream</code>,
+ respectively (see <a href="#5.2">Section 5.2, "Character Type
+ and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class exception: public std::exception
+ {
+ protected:
+ virtual void
+ print (std::ostream&amp;) const = 0;
+ };
+
+ inline std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp; os, const exception&amp; e)
+ {
+ e.print (os);
+ return os;
+ }
+
+
+ class severity
+ {
+ public:
+ enum value
+ {
+ warning,
+ error
+ };
+ };
+
+
+ class error
+ {
+ public:
+ error (xml_schema::severity,
+ const std::string&amp; id,
+ unsigned long line,
+ unsigned long column,
+ const std::string&amp; message);
+
+ xml_schema::severity
+ severity () const;
+
+ const std::string&amp;
+ id () const;
+
+ unsigned long
+ line () const;
+
+ unsigned long
+ column () const;
+
+ const std::string&amp;
+ message () const;
+ };
+
+ std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp;, const error&amp;);
+
+
+ class diagnostics: public std::vector&lt;error>
+ {
+ };
+
+ std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp;, const diagnostics&amp;);
+
+
+ class parsing: public exception
+ {
+ public:
+ parsing ();
+ parsing (const xml_schema::diagnostics&amp;);
+
+ const xml_schema::diagnostics&amp;
+ diagnostics () const;
+
+ virtual const char*
+ what () const throw ();
+
+ protected:
+ virtual void
+ print (std::ostream&amp;) const;
+ };
+}
+ </pre>
+
+ <p>The following example shows how we can catch and print this
+ exception. The code will print diagnostics messages one per line
+ in case of an error.</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ // Parse.
+ }
+ catch (const xml_schema::parsing&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>With the <code>error_handler</code> approach the diagnostics
+ messages are delivered as parsing progresses. The following
+ listing presents the definition of the <code>error_handler</code>
+ interface. Note that if the character type is <code>wchar_t</code>,
+ then the string type in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class error_handler
+ {
+ public:
+ class severity
+ {
+ public:
+ enum value
+ {
+ warning,
+ error,
+ fatal
+ };
+ };
+
+ virtual bool
+ handle (const std::string&amp; id,
+ unsigned long line,
+ unsigned long column,
+ severity,
+ const std::string&amp; message) = 0;
+ };
+}
+ </pre>
+
+ <p>The return value of the <code>handle()</code> function indicates whether
+ parsing should continue if possible. The error with the fatal severity
+ level terminates the parsing process regardless of the returned value.
+ At the end of the parsing process with an error that was reported via
+ the <code>error_handler</code> object, an empty
+ <code>xml_schema::parsing</code> exception is thrown to indicate
+ the failure to the caller. You can alter this behavior by throwing
+ your own exception from the <code>handle()</code> function.</p>
+
+
+ <!-- Appendix A -->
+
+
+ <h1><a name="A">Appendix A &mdash; Supported XML Schema Constructs</a></h1>
+
+ <p>The C++/Parser mapping supports validation of the following W3C XML
+ Schema constructs in the generated code.</p>
+
+ <!-- border="1" is necessary for html2ps -->
+ <table id="features" border="1">
+ <tr><th>Construct</th><th>Notes</th></tr>
+ <tr><th colspan="2">Structure</th></tr>
+
+ <tr><td>element</td><td></td></tr>
+ <tr><td>attribute</td><td></td></tr>
+
+ <tr><td>any</td><td></td></tr>
+ <tr><td>anyAttribute</td><td></td></tr>
+
+ <tr><td>all</td><td></td></tr>
+ <tr><td>sequence</td><td></td></tr>
+ <tr><td>choice</td><td></td></tr>
+
+ <tr><td>complex type, empty content</td><td></td></tr>
+ <tr><td>complex type, mixed content</td><td></td></tr>
+ <tr><td>complex type, simple content extension</td><td></td></tr>
+ <tr><td>complex type, simple content restriction</td>
+ <td>Simple type facets are not validated.</td></tr>
+ <tr><td>complex type, complex content extension</td><td></td></tr>
+ <tr><td>complex type, complex content restriction</td><td></td></tr>
+
+ <tr><td>list</td><td></td></tr>
+
+ <tr><th colspan="2">Datatypes</th></tr>
+
+ <tr><td>byte</td><td></td></tr>
+ <tr><td>unsignedByte</td><td></td></tr>
+ <tr><td>short</td><td></td></tr>
+ <tr><td>unsignedShort</td><td></td></tr>
+ <tr><td>int</td><td></td></tr>
+ <tr><td>unsignedInt</td><td></td></tr>
+ <tr><td>long</td><td></td></tr>
+ <tr><td>unsignedLong</td><td></td></tr>
+ <tr><td>integer</td><td></td></tr>
+ <tr><td>nonPositiveInteger</td><td></td></tr>
+ <tr><td>nonNegativeInteger</td><td></td></tr>
+ <tr><td>positiveInteger</td><td></td></tr>
+ <tr><td>negativeInteger</td><td></td></tr>
+
+ <tr><td>boolean</td><td></td></tr>
+
+ <tr><td>float</td><td></td></tr>
+ <tr><td>double</td><td></td></tr>
+ <tr><td>decimal</td><td></td></tr>
+
+ <tr><td>string</td><td></td></tr>
+ <tr><td>normalizedString</td><td></td></tr>
+ <tr><td>token</td><td></td></tr>
+ <tr><td>Name</td><td></td></tr>
+ <tr><td>NMTOKEN</td><td></td></tr>
+ <tr><td>NCName</td><td></td></tr>
+ <tr><td>language</td><td></td></tr>
+ <tr><td>anyURI</td><td></td></tr>
+
+ <tr><td>ID</td><td>Identity constraint is not enforced.</td></tr>
+ <tr><td>IDREF</td><td>Identity constraint is not enforced.</td></tr>
+
+ <tr><td>NMTOKENS</td><td></td></tr>
+ <tr><td>IDREFS</td><td>Identity constraint is not enforced.</td></tr>
+
+ <tr><td>QName</td><td></td></tr>
+
+ <tr><td>base64Binary</td><td></td></tr>
+ <tr><td>hexBinary</td><td></td></tr>
+
+ <tr><td>date</td><td></td></tr>
+ <tr><td>dateTime</td><td></td></tr>
+ <tr><td>duration</td><td></td></tr>
+ <tr><td>gDay</td><td></td></tr>
+ <tr><td>gMonth</td><td></td></tr>
+ <tr><td>gMonthDay</td><td></td></tr>
+ <tr><td>gYear</td><td></td></tr>
+ <tr><td>gYearMonth</td><td></td></tr>
+ <tr><td>time</td><td></td></tr>
+ </table>
+
+
+ </div>
+</div>
+
+</body>
+</html>
diff --git a/doc/cxx/parser/guide/index.xhtml.in b/doc/cxx/parser/guide/index.xhtml.in
new file mode 100644
index 0000000..119f421
--- /dev/null
+++ b/doc/cxx/parser/guide/index.xhtml.in
@@ -0,0 +1,4163 @@
+<?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++/Parser Mapping Getting Started Guide</title>
+
+ <meta name="copyright" content="&#169; @copyright@"/>
+ <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,parser,validation"/>
+ <meta name="description" content="C++/Parser Mapping Getting Started Guide"/>
+
+ <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%;
+ line-height: 1.2em;
+ }
+
+ h2 {
+ font-weight : bold;
+ font-size : 150%;
+
+ padding-top : 0.8em;
+ }
+
+ h3 {
+ font-size : 140%;
+ 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;
+ }
+
+ #titlepage #first-title {
+ padding: 1em 0 0.4em 0;
+ }
+
+ #titlepage #second-title {
+ padding: 0.4em 0 2em 0;
+ }
+
+ /* Lists */
+ ul.list li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+ ol.steps {
+ padding-left : 1.8em;
+ }
+
+ ol.steps li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+
+ div.img {
+ text-align: center;
+ padding: 2em 0 2em 0;
+ }
+
+ /* */
+ dl dt {
+ padding : 0.8em 0 0 0;
+ }
+
+ /* 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;
+ }
+
+ /* XML Schema features table. */
+ #features {
+ margin: 2em 0 2em 0;
+
+ border-collapse : collapse;
+ border : 1px solid;
+ border-color : #000000;
+
+ font-size : 11px;
+ line-height : 14px;
+ }
+
+ #features th, #features td {
+ border: 1px solid;
+ padding : 0.6em 0.6em 0.6em 0.6em;
+ }
+
+ #features th {
+ background : #cde8f6;
+ }
+
+ #features td {
+ text-align: left;
+ }
+
+
+ /* 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 class="title" id="first-title">C++/Parser Mapping</div>
+ <div class="title" id="second-title">Getting Started Guide</div>
+
+ <p>Copyright &#169; @copyright@.</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/parser/guide/index.xhtml">XHTML</a>,
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.pdf">PDF</a>, and
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/parser/guide/cxx-parser-guide.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>
+ <table class="toc">
+ <tr><th>1.1</th><td><a href="#1.1">Mapping Overview</a></td></tr>
+ <tr><th>1.2</th><td><a href="#1.2">Benefits</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>2</th><td><a href="#2">Hello World Example</a>
+ <table class="toc">
+ <tr><th>2.1</th><td><a href="#2.1">Writing XML Document and Schema</a></td></tr>
+ <tr><th>2.2</th><td><a href="#2.2">Translating Schema to C++</a></td></tr>
+ <tr><th>2.3</th><td><a href="#2.3">Implementing Application Logic</a></td></tr>
+ <tr><th>2.4</th><td><a href="#2.4">Compiling and Running</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>3</th><td><a href="#3">Parser Skeletons</a>
+ <table class="toc">
+ <tr><th>3.1</th><td><a href="#3.1">Implementing the Gender Parser</a></td></tr>
+ <tr><th>3.2</th><td><a href="#3.2">Implementing the Person Parser</a></td></tr>
+ <tr><th>3.3</th><td><a href="#3.3">Implementing the People Parser</a></td></tr>
+ <tr><th>3.4</th><td><a href="#3.4">Connecting the Parsers Together</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>4</th><td><a href="#4">Type Maps</a>
+ <table class="toc">
+ <tr><th>4.1</th><td><a href="#4.1">Object Model</a></td></tr>
+ <tr><th>4.2</th><td><a href="#4.2">Type Map File Format</a></td></tr>
+ <tr><th>4.3</th><td><a href="#4.3">Parser Implementations</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>5</th><td><a href="#5">Mapping Configuration</a>
+ <table class="toc">
+ <tr><th>5.1</th><td><a href="#5.1">C++ Standard</a></td></tr>
+ <tr><th>5.2</th><td><a href="#5.2">Character Type and Encoding</a></td></tr>
+ <tr><th>5.3</th><td><a href="#5.3">Underlying XML Parser</a></td></tr>
+ <tr><th>5.4</th><td><a href="#5.4">XML Schema Validation</a></td></tr>
+ <tr><th>5.5</th><td><a href="#5.5">Support for Polymorphism</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>6</th><td><a href="#6">Built-In XML Schema Type Parsers</a>
+ <table class="toc">
+ <tr><th>6.1</th><td><a href="#6.1"><code>QName</code> Parser</a></td></tr>
+ <tr><th>6.2</th><td><a href="#6.2"><code>NMTOKENS</code> and <code>IDREFS</code> Parsers</a></td></tr>
+ <tr><th>6.3</th><td><a href="#6.3"><code>base64Binary</code> and <code>hexBinary</code> Parsers</a></td></tr>
+ <tr><th>6.4</th><td><a href="#6.4">Time Zone Representation</a></td></tr>
+ <tr><th>6.5</th><td><a href="#6.5"><code>date</code> Parser</a></td></tr>
+ <tr><th>6.6</th><td><a href="#6.6"><code>dateTime</code> Parser</a></td></tr>
+ <tr><th>6.7</th><td><a href="#6.7"><code>duration</code> Parser</a></td></tr>
+ <tr><th>6.8</th><td><a href="#6.8"><code>gDay</code> Parser</a></td></tr>
+ <tr><th>6.9</th><td><a href="#6.9"><code>gMonth</code> Parser</a></td></tr>
+ <tr><th>6.10</th><td><a href="#6.10"><code>gMonthDay</code> Parser</a></td></tr>
+ <tr><th>6.11</th><td><a href="#6.11"><code>gYear</code> Parser</a></td></tr>
+ <tr><th>6.12</th><td><a href="#6.12"><code>gYearMonth</code> Parser</a></td></tr>
+ <tr><th>6.13</th><td><a href="#6.13"><code>time</code> Parser</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>7</th><td><a href="#7">Document Parser and Error Handling</a>
+ <table class="toc">
+ <tr><th>7.1</th><td><a href="#7.1">Xerces-C++ Document Parser</a></td></tr>
+ <tr><th>7.2</th><td><a href="#7.2">Expat Document Parser</a></td></tr>
+ <tr><th>7.3</th><td><a href="#7.3">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th></th><td><a href="#A">Appendix A &mdash; Supported XML Schema Constructs</a></td>
+ </tr>
+
+ </table>
+ </div>
+
+ <h1><a name="0">Preface</a></h1>
+
+ <h2><a name="0.1">About This Document</a></h2>
+
+ <p>The goal of this document is to provide you with an understanding of
+ the C++/Parser programming model and allow you to efficiently evaluate
+ XSD against your project's technical requirements. As such, this
+ document is intended for C++ developers and software architects
+ who are looking for an XML processing solution. Prior experience
+ with XML and C++ is required to understand this document. Basic
+ understanding of XML Schema is advantageous but not expected
+ or required.
+ </p>
+
+
+ <h2><a name="0.2">More Information</a></h2>
+
+ <p>Beyond this guide, you may also find the following sources of
+ information useful:</p>
+
+ <ul class="list">
+ <li><a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a></li>
+
+ <li>The <code>cxx/parser/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</li>
+
+ <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a>
+ mailing list is the place to ask technical questions about XSD and the C++/Parser mapping.
+ Furthermore, the <a href="https://www.codesynthesis.com/pipermail/xsd-users/">archives</a>
+ may already have answers to some of your questions.</li>
+
+ </ul>
+
+ <!-- Introduction -->
+
+ <h1><a name="1">1 Introduction</a></h1>
+
+ <p>Welcome to CodeSynthesis XSD and the C++/Parser mapping. XSD is a
+ cross-platform W3C XML Schema to C++ data binding compiler. C++/Parser
+ is a W3C XML Schema to C++ mapping that represents an XML vocabulary
+ as a set of parser skeletons which you can implement to perform XML
+ processing as required by your application logic.
+ </p>
+
+ <h2><a name="1.1">1.1 Mapping Overview</a></h2>
+
+ <p>The C++/Parser mapping provides event-driven, stream-oriented
+ XML parsing, XML Schema validation, and C++ data binding. It was
+ specifically designed and optimized for high performance and
+ small footprint. Based on the static analysis of the schemas, XSD
+ generates compact, highly-optimized hierarchical state machines
+ that combine data extraction, validation, and even dispatching
+ in a single step. As a result, the generated code is typically
+ 2-10 times faster than general-purpose validating XML parsers
+ while maintaining the lowest static and dynamic memory footprints.
+ </p>
+
+ <p>To speed up application development, the C++/Parser mapping
+ can be instructed to generate sample parser implementations
+ and a test driver which can then be filled with the application
+ logic code. The mapping also provides a wide range of
+ mechanisms for controlling and customizing the generated code.</p>
+
+ <p>The next chapter shows how to create a simple application that uses
+ the C++/Parser mapping to parse, validate, and extract data from a
+ simple XML document. The following chapters show how to
+ use the C++/Parser mapping in more detail.</p>
+
+ <h2><a name="1.2">1.2 Benefits</a></h2>
+
+ <p>Traditional XML access APIs such as Document Object Model (DOM)
+ or Simple API for XML (SAX) have a number of drawbacks that
+ make them less suitable for creating robust and maintainable
+ XML processing applications. These drawbacks include:
+ </p>
+
+ <ul class="list">
+ <li>Generic representation of XML in terms of elements, attributes,
+ and text forces an application developer to write a substantial
+ amount of bridging code that identifies and transforms pieces
+ of information encoded in XML to a representation more suitable
+ for consumption by the application logic.</li>
+
+ <li>String-based flow control defers error detection to runtime.
+ It also reduces code readability and maintainability.</li>
+
+ <li>Lack of type safety because the data is represented
+ as text.</li>
+
+ <li>Resulting applications are hard to debug, change, and
+ maintain.</li>
+ </ul>
+
+ <p>In contrast, statically-typed, vocabulary-specific parser
+ skeletons produced by the C++/Parser mapping allow you to
+ operate in your domain terms instead of the generic elements,
+ attributes, and text. Static typing helps catch errors at
+ compile-time rather than at run-time. Automatic code generation
+ frees you for more interesting tasks (such as doing something
+ useful with the information stored in the XML documents) and
+ minimizes the effort needed to adapt your applications to
+ changes in the document structure. To summarize, the C++/Parser
+ mapping has the following key advantages over generic XML
+ access APIs:</p>
+
+ <ul class="list">
+ <li><b>Ease of use.</b> The generated code hides all the complexity
+ associated with recreating the document structure, maintaining the
+ dispatch state, and converting the data from the text representation
+ to data types suitable for manipulation by the application logic.
+ Parser skeletons also provide a convenient mechanism for building
+ custom in-memory representations.</li>
+
+ <li><b>Natural representation.</b> The generated parser skeletons
+ implement parser callbacks as virtual functions with names
+ corresponding to elements and attributes in XML. As a result,
+ you process the XML data using your domain vocabulary instead
+ of generic elements, attributes, and text.
+ </li>
+
+ <li><b>Concise code.</b> With a separate parser skeleton for each
+ XML Schema type, the application implementation is
+ simpler and thus easier to read and understand.</li>
+
+ <li><b>Safety.</b> The XML data is delivered to parser callbacks as
+ statically typed objects. The parser callbacks themselves are virtual
+ functions. This helps catch programming errors at compile-time
+ rather than at runtime.</li>
+
+ <li><b>Maintainability.</b> Automatic code generation minimizes the
+ effort needed to adapt the application to changes in the
+ document structure. With static typing, the C++ compiler
+ can pin-point the places in the application code that need to be
+ changed.</li>
+
+ <li><b>Efficiency.</b> The generated parser skeletons combine
+ data extraction, validation, and even dispatching in a single
+ step. This makes them much more efficient than traditional
+ architectures with separate stages for validation and data
+ extraction/dispatch.</li>
+ </ul>
+
+ <!-- Hello World Parser -->
+
+
+ <h1><a name="2">2 Hello World Example</a></h1>
+
+ <p>In this chapter we will examine how to parse a very simple XML
+ document using the XSD-generated C++/Parser skeletons.
+ The code presented in this chapter is based on the <code>hello</code>
+ example which can be found in the <code>cxx/parser/</code> directory in
+ the <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</p>
+
+ <h2><a name="2.1">2.1 Writing XML Document and Schema</a></h2>
+
+ <p>First, we need to get an idea about the structure
+ of the XML documents we are going to process. Our
+ <code>hello.xml</code>, for example, could look like this:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello>
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>Then we can write a description of the above XML in the
+ XML Schema language and save it into <code>hello.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello">
+ &lt;xs:sequence>
+ &lt;xs:element name="greeting" type="xs:string"/>
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Even if you are not familiar with XML Schema, it
+ should be easy to connect declarations in <code>hello.xsd</code>
+ to elements in <code>hello.xml</code>. The <code>hello</code> type
+ is defined as a sequence of the nested <code>greeting</code> and
+ <code>name</code> elements. Note that the term sequence in XML
+ Schema means that elements should appear in a particular order
+ as opposed to appearing multiple times. The <code>name</code>
+ element has its <code>maxOccurs</code> property set to
+ <code>unbounded</code> which means it can appear multiple times
+ in an XML document. Finally, the globally-defined <code>hello</code>
+ element prescribes the root element for our vocabulary. For an
+ easily-approachable introduction to XML Schema refer to
+ <a href="http://www.w3.org/TR/xmlschema-0/">XML Schema Part 0:
+ Primer</a>.</p>
+
+ <p>The above schema is a specification of our XML vocabulary; it tells
+ everybody what valid documents of our XML-based language should look
+ like. The next step is to compile this schema to generate
+ the object model and parsing functions.</p>
+
+ <h2><a name="2.2">2.2 Translating Schema to C++</a></h2>
+
+ <p>Now we are ready to translate our <code>hello.xsd</code> to C++ parser
+ skeletons. To do this we invoke the XSD compiler from a terminal
+ (UNIX) or a command prompt (Windows):
+ </p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --xml-parser expat hello.xsd
+ </pre>
+
+ <p>The <code>--xml-parser</code> option indicates that we want to
+ use Expat as the underlying XML parser (see <a href="#5.3">Section
+ 5.3, "Underlying XML Parser"</a>). The XSD compiler produces two
+ C++ files: <code>hello-pskel.hxx</code> and <code>hello-pskel.cxx</code>.
+ The following code fragment is taken from <code>hello-pskel.hxx</code>;
+ it should give you an idea about what gets generated:
+ </p>
+
+ <pre class="c++">
+class hello_pskel
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ greeting (const std::string&amp;);
+
+ virtual void
+ name (const std::string&amp;);
+
+ virtual void
+ post_hello ();
+
+ // Parser construction API.
+ //
+ void
+ greeting_parser (xml_schema::string_pskel&amp;);
+
+ void
+ name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ parsers (xml_schema::string_pskel&amp; /* greeting */,
+ xml_schema::string_pskel&amp; /* name */);
+
+private:
+ ...
+};
+ </pre>
+
+ <p>The first four member functions shown above are called parser
+ callbacks. You would normally override them in your implementation
+ of the parser to do something useful. Let's go through all of
+ them one by one.</p>
+
+ <p>The <code>pre()</code> function is an initialization callback. It is
+ called when a new element of type <code>hello</code> is about
+ to be parsed. You would normally use this function to allocate a new
+ instance of the resulting type or clear accumulators that are used
+ to gather information during parsing. The default implementation
+ of this function does nothing.</p>
+
+ <p>The <code>post_hello()</code> function is a finalization callback. Its
+ name is constructed by adding the parser skeleton name to the
+ <code>post_</code> prefix. The finalization callback is called when
+ parsing of the element is complete and the result, if any, should
+ be returned. Note that in our case the return type of
+ <code>post_hello()</code> is <code>void</code> which means there
+ is nothing to return. More on parser return types later.
+ </p>
+
+ <p>You may be wondering why the finalization callback is called
+ <code>post_hello()</code> instead of <code>post()</code> just
+ like <code>pre()</code>. The reason for this is that
+ finalization callbacks can have different return types and
+ result in function signature clashes across inheritance
+ hierarchies. To prevent this the signatures of finalization
+ callbacks are made unique by adding the type name to their names.</p>
+
+ <p>The <code>greeting()</code> and <code>name()</code> functions are
+ called when the <code>greeting</code> and <code>name</code> elements
+ have been parsed, respectively. Their arguments are of type
+ <code>std::string</code> and contain the data extracted from XML.</p>
+
+ <p>The last three functions are for connecting parsers to each other.
+ For example, there is a predefined parser for built-in XML Schema type
+ <code>string</code> in the XSD runtime. We will be using
+ it to parse the contents of <code>greeting</code> and
+ <code>name</code> elements, as shown in the next section.</p>
+
+ <h2><a name="2.3">2.3 Implementing Application Logic</a></h2>
+
+ <p>At this point we have all the parts we need to do something useful
+ with the information stored in our XML document. The first step is
+ to implement the parser:
+ </p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello-pskel.hxx"
+
+class hello_pimpl: public hello_pskel
+{
+public:
+ virtual void
+ greeting (const std::string&amp; g)
+ {
+ greeting_ = g;
+ }
+
+ virtual void
+ name (const std::string&amp; n)
+ {
+ std::cout &lt;&lt; greeting_ &lt;&lt; ", " &lt;&lt; n &lt;&lt; "!" &lt;&lt; std::endl;
+ }
+
+private:
+ std::string greeting_;
+};
+ </pre>
+
+ <p>We left both <code>pre()</code> and <code>post_hello()</code> with the
+ default implementations; we don't have anything to initialize or
+ return. The rest is pretty straightforward: we store the greeting
+ in a member variable and later, when parsing names, use it to
+ say hello.</p>
+
+ <p>An observant reader my ask what happens if the <code>name</code>
+ element comes before <code>greeting</code>? Don't we need to
+ make sure <code>greeting_</code> was initialized and report
+ an error otherwise? The answer is no, we don't have to do
+ any of this. The <code>hello_pskel</code> parser skeleton
+ performs validation of XML according to the schema from which
+ it was generated. As a result, it will check the order
+ of the <code>greeting</code> and <code>name</code> elements
+ and report an error if it is violated.</p>
+
+ <p>Now it is time to put this parser implementation to work:</p>
+
+ <pre class="c++">
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ // Construct the parser.
+ //
+ xml_schema::string_pimpl string_p;
+ hello_pimpl hello_p;
+
+ hello_p.greeting_parser (string_p);
+ hello_p.name_parser (string_p);
+
+ // Parse the XML instance.
+ //
+ xml_schema::document doc_p (hello_p, "hello");
+
+ hello_p.pre ();
+ doc_p.parse (argv[1]);
+ hello_p.post_hello ();
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>The first part of this code snippet instantiates individual parsers
+ and assembles them into a complete vocabulary parser.
+ <code>xml_schema::string_pimpl</code> is an implementation of a parser
+ for built-in XML Schema type <code>string</code>. It is provided by
+ the XSD runtime along with parsers for other built-in types (for
+ more information on the built-in parsers see <a href="#6">Chapter 6,
+ "Built-In XML Schema Type Parsers"</a>). We use <code>string_pimpl</code>
+ to parse the <code>greeting</code> and <code>name</code> elements as
+ indicated by the calls to <code>greeting_parser()</code> and
+ <code>name_parser()</code>.
+ </p>
+
+ <p>Then we instantiate a document parser (<code>doc_p</code>). The
+ first argument to its constructor is the parser for
+ the root element (<code>hello_p</code> in our case). The
+ second argument is the root element name.
+ </p>
+
+ <p>The final piece is the calls to <code>pre()</code>, <code>parse()</code>,
+ and <code>post_hello()</code>. The call to <code>parse()</code>
+ perform the actual XML parsing while the calls to <code>pre()</code> and
+ <code>post_hello()</code> make sure that the parser for the root
+ element can perform proper initialization and cleanup.</p>
+
+ <p>While our parser implementation and test driver are pretty small and
+ easy to write by hand, for bigger XML vocabularies it can be a
+ substantial effort. To help with this task XSD can automatically
+ generate sample parser implementations and a test driver from your
+ schemas. You can request the generation of a sample implementation with
+ empty function bodies by specifying the <code>--generate-noop-impl</code>
+ option. Or you can generate a sample implementation that prints the
+ data store in XML by using the <code>--generate-print-impl</code>
+ option. To request the generation of a test driver you can use the
+ <code>--generate-test-driver</code> option. For more information
+ on these options refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>. The <code>'generated'</code> example
+ in the <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ shows the sample implementation generation feature in action.</p>
+
+
+ <h2><a name="2.4">2.4 Compiling and Running</a></h2>
+
+ <p>After saving all the parts from the previous section in
+ <code>driver.cxx</code>, we are ready to compile our first
+ application and run it on the test XML document. On a UNIX
+ system this can be done with the following commands:
+ </p>
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx hello-pskel.cxx
+$ c++ -std=c++11 -o driver driver.o hello-pskel.o -lexpat
+$ ./driver hello.xml
+Hello, sun!
+Hello, moon!
+Hello, world!
+ </pre>
+
+ <p>Here <code>.../libxsd</code> represents the path to the
+ <a href="https://cppget.org/libxsd">libxsd</a> package root
+ directory. We can also test the error handling. To test XML
+ well-formedness checking, we can try to parse
+ <code>hello-pskel.hxx</code>:</p>
+
+ <pre class="terminal">
+$ ./driver hello-pskel.hxx
+hello-pskel.hxx:1:0: not well-formed (invalid token)
+ </pre>
+
+ <p>We can also try to parse a valid XML but not from our
+ vocabulary, for example <code>hello.xsd</code>:</p>
+
+ <pre class="terminal">
+$ ./driver hello.xsd
+hello.xsd:2:0: expected element 'hello' instead of
+'http://www.w3.org/2001/XMLSchema#schema'
+ </pre>
+
+
+ <!-- Chapater 3 -->
+
+
+ <h1><a name="3">3 Parser Skeletons</a></h1>
+
+ <p>As we have seen in the previous chapter, the XSD compiler generates
+ a parser skeleton class for each type defined in XML Schema. In
+ this chapter we will take a closer look at different functions
+ that comprise a parser skeleton as well as the way to connect
+ our implementations of these parser skeletons to create a complete
+ parser.</p>
+
+ <p>In this and subsequent chapters we will use the following schema
+ that describes a collection of person records. We save it in
+ <code>people.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:simpleType name="gender">
+ &lt;xs:restriction base="xs:string">
+ &lt;xs:enumeration value="male"/>
+ &lt;xs:enumeration value="female"/>
+ &lt;/xs:restriction>
+ &lt;/xs:simpleType>
+
+ &lt;xs:complexType name="person">
+ &lt;xs:sequence>
+ &lt;xs:element name="first-name" type="xs:string"/>
+ &lt;xs:element name="last-name" type="xs:string"/>
+ &lt;xs:element name="gender" type="gender"/>
+ &lt;xs:element name="age" type="xs:short"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:complexType name="people">
+ &lt;xs:sequence>
+ &lt;xs:element name="person" type="person" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="people" type="people"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>A sample XML instance to go along with this schema is saved
+ in <code>people.xml</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people>
+ &lt;person>
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+ &lt;person>
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+&lt;/people>
+ </pre>
+
+ <p>Compiling <code>people.xsd</code> with the XSD compiler results
+ in three parser skeletons being generated: <code>gender_pskel</code>,
+ <code>person_pskel</code>, and <code>people_pskel</code>. We are going
+ to examine and implement each of them in the subsequent sections.</p>
+
+ <h2><a name="3.1">3.1 Implementing the Gender Parser</a></h2>
+
+ <p>The generated <code>gender_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class gender_pskel: public virtual xml_schema::string_pskel
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ post_gender ();
+};
+ </pre>
+
+ <p>Notice that <code>gender_pskel</code> inherits from
+ <code>xml_schema::string_skel</code> which is a parser skeleton
+ for built-in XML Schema type <code>string</code> and is
+ predefined in the XSD runtime library. This is an example
+ of the general rule that parser skeletons follow: if a type
+ in XML Schema inherits from another then there will be an
+ equivalent inheritance between the corresponding parser
+ skeleton classes.</p>
+
+ <p>The <code>pre()</code> and <code>post_gender()</code> callbacks
+ should look familiar from the previous chapter. Let's now
+ implement the parser. Our implementation will simply print
+ the gender to <code>cout</code>:</p>
+
+
+ <pre class="c++">
+class gender_pimpl: public gender_pskel,
+ public xml_schema::string_pimpl
+{
+public:
+ virtual void
+ post_gender ()
+ {
+ std::string s = post_string ();
+ cout &lt;&lt; "gender: " &lt;&lt; s &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>While the code is quite short, there is a lot going on. First,
+ notice that we are inheriting from <code>gender_pskel</code> <em>and</em>
+ from <code>xml_schema::string_pimpl</code>. We've encountered
+ <code>xml_schema::string_pimpl</code> already; it is an
+ implementation of the <code>xml_schema::string_pskel</code> parser
+ skeleton for built-in XML Schema type <code>string</code>.</p>
+
+ <p>This is another common theme in the C++/Parser programming model:
+ reusing implementations of the base parsers in the derived ones with
+ the C++ mixin idiom. In our case, <code>string_pimpl</code> will
+ do all the dirty work of extracting the data and we can just get
+ it at the end with the call to <code>post_string()</code>.</p>
+
+ <p>In case you are curious, here is what
+ <code>xml_schema::string_pskel</code> and
+ <code>xml_schema::string_pimpl</code> look like:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class string_pskel: public simple_content
+ {
+ public:
+ virtual std::string
+ post_string () = 0;
+ };
+
+ class string_pimpl: public virtual string_pskel
+ {
+ public:
+ virtual void
+ _pre ();
+
+ virtual void
+ _characters (const xml_schema::ro_string&amp;);
+
+ virtual std::string
+ post_string ();
+
+ protected:
+ std::string str_;
+ };
+}
+ </pre>
+
+ <p>There are three new pieces in this code that we haven't seen yet.
+ They are the <code>simple_content</code> class as well as
+ the <code>_pre()</code> and <code>_characters()</code> functions.
+ The <code>simple_content</code> class is defined in the XSD
+ runtime and is a base class for all parser skeletons that conform
+ to the simple content model in XML Schema. Types with the
+ simple content model cannot have nested elements&mdash;only text
+ and attributes. There is also the <code>complex_content</code>
+ class which corresponds to the complex content mode (types with
+ nested elements, for example, <code>person</code> from
+ <code>people.xsd</code>).</p>
+
+ <p>The <code>_pre()</code> function is a parser callback. Remember we
+ talked about the <code>pre()</code> and <code>post_*()</code> callbacks
+ in the previous chapter? There are actually two more callbacks
+ with similar roles: <code>_pre()</code> and <code>_post ()</code>.
+ As a result, each parser skeleton has four special callbacks:</p>
+
+ <pre class="c++">
+ virtual void
+ pre ();
+
+ virtual void
+ _pre ();
+
+ virtual void
+ _post ();
+
+ virtual void
+ post_name ();
+ </pre>
+
+ <p><code>pre()</code> and <code>_pre()</code> are initialization
+ callbacks. They get called in that order before a new instance of the type
+ is about to be parsed. The difference between <code>pre()</code> and
+ <code>_pre()</code> is conventional: <code>pre()</code> can
+ be completely overridden by a derived parser. The derived
+ parser can also override <code>_pre()</code> but has to always call
+ the original version. This allows you to partition initialization
+ into customizable and required parts.</p>
+
+ <p>Similarly, <code>_post()</code> and <code>post_name()</code> are
+ finalization callbacks with exactly the same semantics:
+ <code>post_name()</code> can be completely overridden by the derived
+ parser while the original <code>_post()</code> should always be called.
+ </p>
+
+ <p>The final bit we need to discuss in this section is the
+ <code>_characters()</code> function. As you might have guessed, it
+ is also a callback. A low-level one that delivers raw character content
+ for the type being parsed. You will seldom need to use this callback
+ directly. Using implementations for the built-in parsers provided by
+ the XSD runtime is usually a simpler and more convenient
+ alternative.</p>
+
+ <p>At this point you might be wondering why some <code>post_*()</code>
+ callbacks, for example <code>post_string()</code>, return some data
+ while others, for example <code>post_gender()</code>, have
+ <code>void</code> as a return type. This is a valid concern
+ and it will be addressed in the next chapter.</p>
+
+ <h2><a name="3.2">3.2 Implementing the Person Parser</a></h2>
+
+ <p>The generated <code>person_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class person_pskel: public xml_schema::complex_content
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ first_name (const std::string&amp;);
+
+ virtual void
+ last_name (const std::string&amp;);
+
+ virtual void
+ gender ();
+
+ virtual void
+ age (short);
+
+ virtual void
+ post_person ();
+
+ // Parser construction API.
+ //
+ void
+ first_name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ last_name_parser (xml_schema::string_pskel&amp;);
+
+ void
+ gender_parser (gender_pskel&amp;);
+
+ void
+ age_parser (xml_schema::short_pskel&amp;);
+
+ void
+ parsers (xml_schema::string_pskel&amp; /* first-name */,
+ xml_schema::string_pskel&amp; /* last-name */,
+ gender_pskel&amp; /* gender */,
+ xml_schema::short_pskel&amp; /* age */);
+};
+ </pre>
+
+
+ <p>As you can see, we have a parser callback for each of the nested
+ elements found in the <code>person</code> XML Schema type.
+ The implementation of this parser is straightforward:</p>
+
+ <pre class="c++">
+class person_pimpl: public person_pskel
+{
+public:
+ virtual void
+ first_name (const std::string&amp; n)
+ {
+ cout &lt;&lt; "first: " &lt;&lt; f &lt;&lt; endl;
+ }
+
+ virtual void
+ last_name (const std::string&amp; l)
+ {
+ cout &lt;&lt; "last: " &lt;&lt; l &lt;&lt; endl;
+ }
+
+ virtual void
+ age (short a)
+ {
+ cout &lt;&lt; "age: " &lt;&lt; a &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Notice that we didn't override the <code>gender()</code> callback
+ because all the printing is done by <code>gender_pimpl</code>.</p>
+
+
+ <h2><a name="3.3">3.3 Implementing the People Parser</a></h2>
+
+ <p>The generated <code>people_pskel</code> parser skeleton looks like
+ this:</p>
+
+ <pre class="c++">
+class people_pskel: public xml_schema::complex_content
+{
+public:
+ // Parser callbacks. Override them in your implementation.
+ //
+ virtual void
+ pre ();
+
+ virtual void
+ person ();
+
+ virtual void
+ post_people ();
+
+ // Parser construction API.
+ //
+ void
+ person_parser (person_pskel&amp;);
+
+ void
+ parsers (person_pskel&amp; /* person */);
+};
+ </pre>
+
+ <p>The <code>person()</code> callback will be called after parsing each
+ <code>person</code> element. While <code>person_pimpl</code> does
+ all the printing, one useful thing we can do in this callback is to
+ print an extra newline after each person record so that our
+ output is more readable:</p>
+
+ <pre class="c++">
+class people_pimpl: public people_pskel
+{
+public:
+ virtual void
+ person ()
+ {
+ cout &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Now it is time to put everything together.</p>
+
+
+ <h2><a name="3.4">3.4 Connecting the Parsers Together</a></h2>
+
+ <p>At this point we have all the individual parsers implemented
+ and can proceed to assemble them into a complete parser
+ for our XML vocabulary. The first step is to instantiate
+ all the individual parsers that we will need:</p>
+
+ <pre class="c++">
+xml_schema::short_pimpl short_p;
+xml_schema::string_pimpl string_p;
+
+gender_pimpl gender_p;
+person_pimpl person_p;
+people_pimpl people_p;
+ </pre>
+
+ <p>Notice that our schema uses two built-in XML Schema types:
+ <code>string</code> for the <code>first-name</code> and
+ <code>last-name</code> elements as well as <code>short</code>
+ for <code>age</code>. We will use predefined parsers that
+ come with the XSD runtime to handle these types. The next
+ step is to connect all the individual parsers. We do this
+ with the help of functions defined in the parser
+ skeletons and marked with the "Parser Construction API"
+ comment. One way to do it is to connect each individual
+ parser by calling the <code>*_parser()</code> functions:</p>
+
+ <pre class="c++">
+person_p.first_name_parser (string_p);
+person_p.last_name_parser (string_p);
+person_p.gender_parser (gender_p);
+person_p.age_parser (short_p);
+
+people_p.person_parser (person_p);
+ </pre>
+
+ <p>You might be wondering what happens if you do not provide
+ a parser by not calling one of the <code>*_parser()</code> functions.
+ In that case the corresponding XML content will be skipped,
+ including validation. This is an efficient way to ignore parts
+ of the document that you are not interested in.</p>
+
+
+ <p>An alternative, shorter, way to connect the parsers is by using
+ the <code>parsers()</code> functions which connects all the parsers
+ for a given type at once:</p>
+
+ <pre class="c++">
+person_p.parsers (string_p, string_p, gender_p, short_p);
+people_p.parsers (person_p);
+ </pre>
+
+ <p>The following figure illustrates the resulting connections. Notice
+ the correspondence between return types of the <code>post_*()</code>
+ functions and argument types of element callbacks that are connected
+ by the arrows.</p>
+
+ <!-- align=center is needed for html2ps -->
+ <div class="img" align="center"><img src="figure-1.png"/></div>
+
+ <p>The last step is the construction of the document parser and
+ invocation of the complete parser on our sample XML instance:</p>
+
+ <pre class="c++">
+xml_schema::document doc_p (people_p, "people");
+
+people_p.pre ();
+doc_p.parse ("people.xml");
+people_p.post_people ();
+ </pre>
+
+ <p>Let's consider <code>xml_schema::document</code> in
+ more detail. While the exact definition of this class
+ varies depending on the underlying parser selected,
+ here is the common part:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class document
+ {
+ public:
+ document (xml_schema::parser_base&amp;,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (xml_schema::parser_base&amp;,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ void
+ parse (const std::string&amp; file);
+
+ void
+ parse (std::istream&amp;);
+
+ ...
+
+ };
+}
+ </pre>
+
+ <p><code>xml_schema::document</code> is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element (<code>people_impl</code>
+ in our case). Because a type parser is only concerned with
+ the element's content and not with the element's name, we need
+ to specify the root element's name somewhere. That's
+ what is passed as the second and third arguments to the
+ <code>document</code>'s constructors.</p>
+
+ <p>There are also two overloaded <code>parse()</code> functions
+ defined in the <code>document</code> class (there are actually
+ more but the others are specific to the underlying XML parser).
+ The first version parses a local file identified by a name. The
+ second version reads the data from an input stream. For more
+ information on the <code>xml_schema::document</code> class
+ refer to <a href="#7">Chapter 7, "Document Parser and Error
+ Handling"</a>.</p>
+
+ <p>Let's now consider a step-by-step list of actions that happen
+ as we parse through <code>people.xml</code>. The content of
+ <code>people.xml</code> is repeated below for convenience.</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people>
+ &lt;person>
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+ &lt;person>
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+&lt;/people>
+ </pre>
+
+
+ <ol class="steps">
+ <li><code>people_p.pre()</code> is called from
+ <code>main()</code>. We did not provide any implementation
+ for this callback so this call is a no-op.</li>
+
+ <li><code>doc_p.parse("people.xml")</code> is called from
+ <code>main()</code>. The parser opens the file and starts
+ parsing its content.</li>
+
+ <li>The parser encounters the root element. <code>doc_p</code>
+ verifies that the root element is correct and calls
+ <code>_pre()</code> on <code>people_p</code> which is also
+ a no-op. Parsing is now delegated to <code>people_p</code>.</li>
+
+ <li>The parser encounters the <code>person</code> element.
+ <code>people_p</code> determines that <code>person_p</code>
+ is responsible for parsing this element. <code>pre()</code>
+ and <code>_pre()</code> callbacks are called on <code>person_p</code>.
+ Parsing is now delegated to <code>person_p</code>.</li>
+
+ <li>The parser encounters the <code>first-name</code> element.
+ <code>person_p</code> determines that <code>string_p</code>
+ is responsible for parsing this element. <code>pre()</code>
+ and <code>_pre()</code> callbacks are called on <code>string_p</code>.
+ Parsing is now delegated to <code>string_p</code>.</li>
+
+ <li>The parser encounters character content consisting of
+ <code>"John"</code>. The <code>_characters()</code> callback is
+ called on <code>string_p</code>.</li>
+
+ <li>The parser encounters the end of <code>first-name</code>
+ element. The <code>_post()</code> and <code>post_string()</code>
+ callbacks are called on <code>string_p</code>. The
+ <code>first_name()</code> callback is called on <code>person_p</code>
+ with the return value of <code>post_string()</code>. The
+ <code>first_name()</code> implementation prints
+ <code>"first: John"</code> to <code>cout</code>.
+ Parsing is now returned to <code>person_p</code>.</li>
+
+ <li>Steps analogous to 5-7 are performed for the <code>last-name</code>,
+ <code>gender</code>, and <code>age</code> elements.</li>
+
+ <li>The parser encounters the end of <code>person</code>
+ element. The <code>_post()</code> and <code>post_person()</code>
+ callbacks are called on <code>person_p</code>. The
+ <code>person()</code> callback is called on <code>people_p</code>.
+ The <code>person()</code> implementation prints a new line
+ to <code>cout</code>. Parsing is now returned to
+ <code>people_p</code>.</li>
+
+ <li>Steps 4-9 are performed for the second <code>person</code>
+ element.</li>
+
+ <li>The parser encounters the end of <code>people</code>
+ element. The <code>_post()</code> callback is called on
+ <code>people_p</code>. The <code>doc_p.parse("people.xml")</code>
+ call returns to <code>main()</code>.</li>
+
+ <li><code>people_p.post_people()</code> is called from
+ <code>main()</code> which is a no-op.</li>
+
+ </ol>
+
+
+ <!-- Chpater 4 -->
+
+
+ <h1><a name="4">4 Type Maps</a></h1>
+
+ <p>There are many useful things you can do inside parser callbacks as they
+ are right now. There are, however, times when you want to propagate
+ some information from one parser to another or to the caller of the
+ parser. One common task that would greatly benefit from such a
+ possibility is building a tree-like in-memory object model of the
+ data stored in XML. During execution, each individual sub-parser
+ would create a sub-tree and return it to its <em>parent</em> parser
+ which can then incorporate this sub-tree into the whole tree.</p>
+
+ <p>In this chapter we will discuss the mechanisms offered by the
+ C++/Parser mapping for returning information from individual
+ parsers and see how to use them to build an object model
+ of our people vocabulary.</p>
+
+ <h2><a name="4.1">4.1 Object Model</a></h2>
+
+ <p>An object model for our person record example could
+ look like this (saved in the <code>people.hxx</code> file):</p>
+
+ <pre class="c++">
+#include &lt;string>
+#include &lt;vector>
+
+enum gender
+{
+ male,
+ female
+};
+
+class person
+{
+public:
+ person (const std::string&amp; first,
+ const std::string&amp; last,
+ ::gender gender,
+ short age)
+ : first_ (first), last_ (last),
+ gender_ (gender), age_ (age)
+ {
+ }
+
+ const std::string&amp;
+ first () const
+ {
+ return first_;
+ }
+
+ const std::string&amp;
+ last () const
+ {
+ return last_;
+ }
+
+ ::gender
+ gender () const
+ {
+ return gender_;
+ }
+
+ short
+ age () const
+ {
+ return age_;
+ }
+
+private:
+ std::string first_;
+ std::string last_;
+ ::gender gender_;
+ short age_;
+};
+
+typedef std::vector&lt;person> people;
+ </pre>
+
+ <p>While it is clear which parser is responsible for which part of
+ the object model, it is not exactly clear how, for
+ example, <code>gender_pimpl</code> will deliver <code>gender</code>
+ to <code>person_pimpl</code>. You might have noticed that
+ <code>string_pimpl</code> manages to deliver its value to the
+ <code>first_name()</code> callback of <code>person_pimpl</code>. Let's
+ see how we can utilize the same mechanism to propagate our
+ own data.</p>
+
+ <p>There is a way to tell the XSD compiler that you want to
+ exchange data between parsers. More precisely, for each
+ type defined in XML Schema, you can tell the compiler two things.
+ First, the return type of the <code>post_*()</code> callback
+ in the parser skeleton generated for this type. And, second,
+ the argument type for callbacks corresponding to elements and
+ attributes of this type. For example, for XML Schema type
+ <code>gender</code> we can specify the return type for
+ <code>post_gender()</code> in the <code>gender_pskel</code>
+ skeleton and the argument type for the <code>gender()</code> callback
+ in the <code>person_pskel</code> skeleton. As you might have guessed,
+ the generated code will then pass the return value from the
+ <code>post_*()</code> callback as an argument to the element or
+ attribute callback.</p>
+
+ <p>The way to tell the XSD compiler about these XML Schema to
+ C++ mappings is with type map files. Here is a simple type
+ map for the <code>gender</code> type from the previous paragraph:</p>
+
+ <pre class="type-map">
+include "people.hxx";
+gender ::gender ::gender;
+ </pre>
+
+ <p>The first line indicates that the generated code must include
+ <code>people.hxx</code> in order to get the definition for the
+ <code>gender</code> type. The second line specifies that both
+ argument and return types for the <code>gender</code>
+ XML Schema type should be the <code>::gender</code> C++ enum
+ (we use fully-qualified C++ names to avoid name clashes).
+ The next section will describe the type map format in detail.
+ We save this type map in <code>people.map</code> and
+ then translate our schemas with the <code>--type-map</code>
+ option to let the XSD compiler know about our type map:</p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --type-map people.map people.xsd
+ </pre>
+
+ <p>If we now look at the generated <code>people-pskel.hxx</code>,
+ we will see the following changes in the <code>gender_pskel</code> and
+ <code>person_pskel</code> skeletons:</p>
+
+ <pre class="c++">
+#include "people.hxx"
+
+class gender_pskel: public virtual xml_schema::string_pskel
+{
+ virtual ::gender
+ post_gender () = 0;
+
+ ...
+};
+
+class person_pskel: public xml_schema::complex_content
+{
+ virtual void
+ gender (::gender);
+
+ ...
+};
+ </pre>
+
+ <p>Notice that <code>#include "people.hxx"</code> was added to
+ the generated header file from the type map to provide the
+ definition for the <code>gender</code> enum.</p>
+
+ <h2><a name="4.2">4.2 Type Map File Format</a></h2>
+
+ <p>Type map files are used to define a mapping between XML Schema
+ and C++ types. The compiler uses this information
+ to determine return types of <code>post_*()</code>
+ callbacks in parser skeletons corresponding to XML Schema
+ types as well as argument types for callbacks corresponding
+ to elements and attributes of these types.</p>
+
+ <p>The compiler has a set of predefined mapping rules that map
+ the built-in XML Schema types to suitable C++ types (discussed
+ below) and all other types to <code>void</code>.
+ By providing your own type maps you can override these predefined
+ rules. The format of the type map file is presented below:
+ </p>
+
+ <pre class="type-map">
+namespace &lt;schema-namespace> [&lt;cxx-namespace>]
+{
+ (include &lt;file-name>;)*
+ ([type] &lt;schema-type> &lt;cxx-ret-type> [&lt;cxx-arg-type>];)*
+}
+ </pre>
+
+ <p>Both <code><i>&lt;schema-namespace></i></code> and
+ <code><i>&lt;schema-type></i></code> are regex patterns while
+ <code><i>&lt;cxx-namespace></i></code>,
+ <code><i>&lt;cxx-ret-type></i></code>, and
+ <code><i>&lt;cxx-arg-type></i></code> are regex pattern
+ substitutions. All names can be optionally enclosed in
+ <code>" "</code>, for example, to include white-spaces.</p>
+
+ <p><code><i>&lt;schema-namespace></i></code> determines XML
+ Schema namespace. Optional <code><i>&lt;cxx-namespace></i></code>
+ is prefixed to every C++ type name in this namespace declaration.
+ <code><i>&lt;cxx-ret-type></i></code> is a C++ type name that is
+ used as a return type for the <code>post_*()</code> callback.
+ Optional <code><i>&lt;cxx-arg-type></i></code> is an argument
+ type for callbacks corresponding to elements and attributes
+ of this type. If <code><i>&lt;cxx-arg-type></i></code> is not
+ specified, it defaults to <code><i>&lt;cxx-ret-type></i></code>
+ if <code><i>&lt;cxx-ret-type></i></code> ends with <code>*</code> or
+ <code>&amp;</code> (that is, it is a pointer or a reference) and
+ <code>const&nbsp;<i>&lt;cxx-ret-type></i>&amp;</code>
+ otherwise.
+ <code><i>&lt;file-name></i></code> is a file name either in the
+ <code>" "</code> or <code>&lt; ></code> format
+ and is added with the <code>#include</code> directive to
+ the generated code.</p>
+
+ <p>The <code><b>#</b></code> character starts a comment that ends
+ with a new line or end of file. To specify a name that contains
+ <code><b>#</b></code> enclose it in <code><b>" "</b></code>.
+ For example:</p>
+
+ <pre>
+namespace http://www.example.com/xmlns/my my
+{
+ include "my.hxx";
+
+ # Pass apples by value.
+ #
+ apple apple;
+
+ # Pass oranges as pointers.
+ #
+ orange orange_t*;
+}
+ </pre>
+
+ <p>In the example above, for the
+ <code>http://www.example.com/xmlns/my#orange</code>
+ XML Schema type, the <code>my::orange_t*</code> C++ type will
+ be used as both return and argument types.</p>
+
+ <p>Several namespace declarations can be specified in a single
+ file. The namespace declaration can also be completely
+ omitted to map types in a schema without a namespace. For
+ instance:</p>
+
+ <pre class="type-map">
+include "my.hxx";
+apple apple;
+
+namespace http://www.example.com/xmlns/my
+{
+ orange "const orange_t*";
+}
+ </pre>
+
+ <p>The compiler has a number of predefined mapping rules for
+ the built-in XML Schema types which can be presented as the
+ following map files. The string-based XML Schema types are
+ mapped to either <code>std::string</code> or
+ <code>std::wstring</code> depending on the character type
+ selected (see <a href="#5.2"> Section 5.2, "Character Type and
+ Encoding"</a> for more information). The binary XML Schema
+ types are mapped to either <code>std::unique_ptr&lt;xml_schema::buffer></code>
+ or <code>std::auto_ptr&lt;xml_schema::buffer></code>
+ depending on the C++ standard selected (C++11 or C++98,
+ respectively; refer to the <code>--std</code> XSD compiler
+ command line option for details).</p>
+
+ <pre class="type-map">
+namespace http://www.w3.org/2001/XMLSchema
+{
+ boolean bool bool;
+
+ byte "signed char" "signed char";
+ unsignedByte "unsigned char" "unsigned char";
+
+ short short short;
+ unsignedShort "unsigned short" "unsigned short";
+
+ int int int;
+ unsignedInt "unsigned int" "unsigned int";
+
+ long "long long" "long long";
+ unsignedLong "unsigned long long" "unsigned long long";
+
+ integer "long long" "long long";
+
+ negativeInteger "long long" "long long";
+ nonPositiveInteger "long long" "long long";
+
+ positiveInteger "unsigned long long" "unsigned long long";
+ nonNegativeInteger "unsigned long long" "unsigned long long";
+
+ float float float;
+ double double double;
+ decimal double double;
+
+ string std::string;
+ normalizedString std::string;
+ token std::string;
+ Name std::string;
+ NMTOKEN std::string;
+ NCName std::string;
+ ID std::string;
+ IDREF std::string;
+ language std::string;
+ anyURI std::string;
+
+ NMTOKENS xml_schema::string_sequence;
+ IDREFS xml_schema::string_sequence;
+
+ QName xml_schema::qname;
+
+ base64Binary std::[unique|auto]_ptr&lt;xml_schema::buffer>
+ std::[unique|auto]_ptr&lt;xml_schema::buffer>;
+ hexBinary std::[unique|auto]_ptr&lt;xml_schema::buffer>
+ std::[unique|auto]_ptr&lt;xml_schema::buffer>;
+
+ date xml_schema::date;
+ dateTime xml_schema::date_time;
+ duration xml_schema::duration;
+ gDay xml_schema::gday;
+ gMonth xml_schema::gmonth;
+ gMonthDay xml_schema::gmonth_day;
+ gYear xml_schema::gyear;
+ gYearMonth xml_schema::gyear_month;
+ time xml_schema::time;
+}
+ </pre>
+
+ <p>For more information about the mapping of the built-in XML Schema types
+ to C++ types refer to <a href="#6">Chapter 6, "Built-In XML Schema Type
+ Parsers"</a>. The last predefined rule maps anything that wasn't
+ mapped by previous rules to <code>void</code>:</p>
+
+ <pre class="type-map">
+namespace .*
+{
+ .* void void;
+}
+ </pre>
+
+
+ <p>When you provide your own type maps with the
+ <code>--type-map</code> option, they are evaluated first. This
+ allows you to selectively override any of the predefined rules.
+ Note also that if you change the mapping
+ of a built-in XML Schema type then it becomes your responsibility
+ to provide the corresponding parser skeleton and implementation
+ in the <code>xml_schema</code> namespace. You can include the
+ custom definitions into the generated header file using the
+ <code>--hxx-prologue-*</code> options.</p>
+
+ <h2><a name="4.3">4.3 Parser Implementations</a></h2>
+
+ <p>With the knowledge from the previous section, we can proceed
+ with creating a type map that maps types in the <code>people.xsd</code>
+ schema to our object model classes in
+ <code>people.hxx</code>. In fact, we already have the beginning
+ of our type map file in <code>people.map</code>. Let's extend
+ it with the rest of the types:</p>
+
+ <pre class="type-map">
+include "people.hxx";
+
+gender ::gender ::gender;
+person ::person;
+people ::people;
+ </pre>
+
+ <p>There are a few things to note about this type map. We did not
+ provide the argument types for <code>person</code> and
+ <code>people</code> because the default constant reference is
+ exactly what we need. We also did not provide any mappings
+ for built-in XML Schema types <code>string</code> and
+ <code>short</code> because they are handled by the predefined
+ rules and we are happy with the result. Note also that
+ all C++ types are fully qualified. This is done to avoid
+ potential name conflicts in the generated code. Now we can
+ recompile our schema and move on to implementing the parsers:</p>
+
+ <pre class="terminal">
+$ xsd cxx-parser --xml-parser expat --type-map people.map people.xsd
+ </pre>
+
+ <p>Here is the implementation of our three parsers in full. One
+ way to save typing when implementing your own parsers is
+ to open the generated code and copy the signatures of parser
+ callbacks into your code. Or you could always auto generate the
+ sample implementations and fill them with your code.</p>
+
+
+ <pre class="c++">
+#include "people-pskel.hxx"
+
+class gender_pimpl: public gender_pskel,
+ public xml_schema::string_pimpl
+{
+public:
+ virtual ::gender
+ post_gender ()
+ {
+ return post_string () == "male" ? male : female;
+ }
+};
+
+class person_pimpl: public person_pskel
+{
+public:
+ virtual void
+ first_name (const std::string&amp; f)
+ {
+ first_ = f;
+ }
+
+ virtual void
+ last_name (const std::string&amp; l)
+ {
+ last_ = l;
+ }
+
+ virtual void
+ gender (::gender g)
+ {
+ gender_ = g;
+ }
+
+ virtual void
+ age (short a)
+ {
+ age_ = a;
+ }
+
+ virtual ::person
+ post_person ()
+ {
+ return ::person (first_, last_, gender_, age_);
+ }
+
+private:
+ std::string first_;
+ std::string last_;
+ ::gender gender_;
+ short age_;
+};
+
+class people_pimpl: public people_pskel
+{
+public:
+ virtual void
+ person (const ::person&amp; p)
+ {
+ people_.push_back (p);
+ }
+
+ virtual ::people
+ post_people ()
+ {
+ ::people r;
+ r.swap (people_);
+ return r;
+ }
+
+private:
+ ::people people_;
+};
+ </pre>
+
+ <p>This code fragment should look familiar by now. Just note that
+ all the <code>post_*()</code> callbacks now have return types instead
+ of <code>void</code>. Here is the implementation of the test
+ driver for this example:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ // Construct the parser.
+ //
+ xml_schema::short_pimpl short_p;
+ xml_schema::string_pimpl string_p;
+
+ gender_pimpl gender_p;
+ person_pimpl person_p;
+ people_pimpl people_p;
+
+ person_p.parsers (string_p, string_p, gender_p, short_p);
+ people_p.parsers (person_p);
+
+ // Parse the document to obtain the object model.
+ //
+ xml_schema::document doc_p (people_p, "people");
+
+ people_p.pre ();
+ doc_p.parse (argv[1]);
+ people ppl = people_p.post_people ();
+
+ // Print the object model.
+ //
+ for (people::iterator i (ppl.begin ()); i != ppl.end (); ++i)
+ {
+ cout &lt;&lt; "first: " &lt;&lt; i->first () &lt;&lt; endl
+ &lt;&lt; "last: " &lt;&lt; i->last () &lt;&lt; endl
+ &lt;&lt; "gender: " &lt;&lt; (i->gender () == male ? "male" : "female") &lt;&lt; endl
+ &lt;&lt; "age: " &lt;&lt; i->age () &lt;&lt; endl
+ &lt;&lt; endl;
+ }
+}
+ </pre>
+
+ <p>The parser creation and assembly part is exactly the same as in
+ the previous chapter. The parsing part is a bit different:
+ <code>post_people()</code> now has a return value which is the
+ complete object model. We store it in the
+ <code>ppl</code> variable. The last bit of the code simply iterates
+ over the <code>people</code> vector and prints the information
+ for each person. We save the last two code fragments to
+ <code>driver.cxx</code> and proceed to compile and test
+ our new application:</p>
+
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx people-pskel.cxx
+$ c++ -std=c++11 -o driver driver.o people-pskel.o -lexpat
+$ ./driver people.xml
+first: John
+last: Doe
+gender: male
+age: 32
+
+first: Jane
+last: Doe
+gender: female
+age: 28
+ </pre>
+
+
+ <!-- Mapping Configuration -->
+
+
+ <h1><a name="5">5 Mapping Configuration</a></h1>
+
+ <p>The C++/Parser mapping has a number of configuration parameters that
+ determine the overall properties and behavior of the generated code.
+ Configuration parameters are specified with the XSD command line
+ options and include the C++ standard, the character type that is used
+ by the generated code, the underlying XML parser, whether the XML Schema
+ validation is performed in the generated code, and support for XML Schema
+ polymorphism. This chapter describes these configuration
+ parameters in more detail. For more ways to configure the generated
+ code refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>.
+ </p>
+
+ <h2><a name="5.1">5.1 C++ Standard</a></h2>
+
+ <p>The C++/Parser mapping provides support for ISO/IEC C++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</p>
+
+ <h2><a name="5.2">5.2 Character Type and Encoding</a></h2>
+
+ <p>The C++/Parser mapping has built-in support for two character types:
+ <code>char</code> and <code>wchar_t</code>. You can select the
+ character type with the <code>--char-type</code> command line
+ option. The default character type is <code>char</code>. The
+ string-based built-in XML Schema types are returned as either
+ <code>std::string</code> or <code>std::wstring</code> depending
+ on the character type selected.</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. You can select which encoding should be used
+ in the object model 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>
+
+ <p>Note also that the character encoding that is used in the object model
+ is independent of the encodings used in input and output XML. In fact,
+ all three (object mode, input XML, and output XML) can have different
+ encodings.</p>
+
+ <h2><a name="5.3">5.3 Underlying XML Parser</a></h2>
+
+ <p>The C++/Parser mapping can be used with either Xerces-C++ or Expat
+ as the underlying XML parser. You can select the XML parser with
+ the <code>--xml-parser</code> command line option. Valid values
+ for this option are <code>xerces</code> and <code>expat</code>.
+ The default XML parser is Xerces-C++.</p>
+
+ <p>The generated code is identical for both parsers except for the
+ <code>xml_schema::document</code> class in which some of the
+ <code>parse()</code> functions are parser-specific as described
+ in <a href="#7">Chapter 7, "Document Parser and Error Handling"</a>.</p>
+
+
+ <h2><a name="5.4">5.4 XML Schema Validation</a></h2>
+
+ <p>The C++/Parser mapping provides support for validating a
+ commonly-used subset of W3C XML Schema in the generated code.
+ For the list of supported XML Schema constructs refer to
+ <a href="#A">Appendix A, "Supported XML Schema Constructs"</a>.</p>
+
+ <p>By default validation in the generated code is disabled if
+ the underlying XML parser is validating (Xerces-C++) and
+ enabled otherwise (Expat). See <a href="#5.3">Section 5.3,
+ "Underlying XML Parser"</a> for more information about
+ the underlying XML parser. You can override the default
+ behavior with the <code>--generate-validation</code>
+ and <code>--suppress-validation</code> command line options.</p>
+
+
+ <h2><a name="5.5">5.5 Support for Polymorphism</a></h2>
+
+ <p>By default the XSD compiler generates non-polymorphic code. If your
+ vocabulary uses XML Schema polymorphism in the form of <code>xsi:type</code>
+ and/or substitution groups, then you will need to compile your schemas
+ with the <code>--generate-polymorphic</code> option to produce
+ polymorphism-aware code as well as pass <code>true</code> as the last
+ argument to the <code>xml_schema::document</code>'s constructors.</p>
+
+ <p>When using the polymorphism-aware generated code, you can specify
+ several parsers for a single element by passing a parser map
+ instead of an individual parser to the parser connection function
+ for the element. One of the parsers will then be looked up and used
+ depending on the <code>xsi:type</code> attribute value or an element
+ name from a substitution group. Consider the following schema as an
+ example:</p>
+
+ <pre class="xml">
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="person">
+ &lt;xs:sequence>
+ &lt;xs:element name="name" type="xs:string"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;!-- substitution group root -->
+ &lt;xs:element name="person" type="person"/>
+
+ &lt;xs:complexType name="superman">
+ &lt;xs:complexContent>
+ &lt;xs:extension base="person">
+ &lt;xs:attribute name="can-fly" type="xs:boolean"/>
+ &lt;/xs:extension>
+ &lt;/xs:complexContent>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="superman"
+ type="superman"
+ substitutionGroup="person"/>
+
+ &lt;xs:complexType name="batman">
+ &lt;xs:complexContent>
+ &lt;xs:extension base="superman">
+ &lt;xs:attribute name="wing-span" type="xs:unsignedInt"/>
+ &lt;/xs:extension>
+ &lt;/xs:complexContent>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="batman"
+ type="batman"
+ substitutionGroup="superman"/>
+
+ &lt;xs:complexType name="supermen">
+ &lt;xs:sequence>
+ &lt;xs:element ref="person" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="supermen" type="supermen"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Conforming XML documents can use the <code>superman</code>
+ and <code>batman</code> types in place of the <code>person</code>
+ type either by specifying the type with the <code>xsi:type</code>
+ attributes or by using the elements from the substitution
+ group, for instance:</p>
+
+
+ <pre class="xml">
+&lt;supermen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+ &lt;person>
+ &lt;name>John Doe&lt;/name>
+ &lt;/person>
+
+ &lt;superman can-fly="false">
+ &lt;name>James "007" Bond&lt;/name>
+ &lt;/superman>
+
+ &lt;superman can-fly="true" wing-span="10" xsi:type="batman">
+ &lt;name>Bruce Wayne&lt;/name>
+ &lt;/superman>
+
+&lt;/supermen>
+ </pre>
+
+ <p>To print the data stored in such XML documents we can implement
+ the parsers as follows:</p>
+
+ <pre class="c++">
+class person_pimpl: public virtual person_pskel
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse person" &lt;&lt; endl;
+ }
+
+ virtual void
+ name (const std::string&amp; v)
+ {
+ cout &lt;&lt; "name: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_person ()
+ {
+ cout &lt;&lt; "finished parsing person" &lt;&lt; endl;
+ }
+};
+
+class superman_pimpl: public virtual superman_pskel,
+ public person_pimpl
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse superman" &lt;&lt; endl;
+ }
+
+ virtual void
+ can_fly (bool v)
+ {
+ cout &lt;&lt; "can-fly: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_person ()
+ {
+ post_superman ();
+ }
+
+ virtual void
+ post_superman ()
+ {
+ cout &lt;&lt; "finished parsing superman" &lt;&lt; endl
+ }
+};
+
+class batman_pimpl: public virtual batman_pskel,
+ public superman_pimpl
+{
+public:
+ virtual void
+ pre ()
+ {
+ cout &lt;&lt; "starting to parse batman" &lt;&lt; endl;
+ }
+
+ virtual void
+ wing_span (unsigned int v)
+ {
+ cout &lt;&lt; "wing-span: " &lt;&lt; v &lt;&lt; endl;
+ }
+
+ virtual void
+ post_superman ()
+ {
+ post_batman ();
+ }
+
+ virtual void
+ post_batman ()
+ {
+ cout &lt;&lt; "finished parsing batman" &lt;&lt; endl;
+ }
+};
+ </pre>
+
+ <p>Note that because the derived type parsers (<code>superman_pskel</code>
+ and <code>batman_pskel</code>) are called via the <code>person_pskel</code>
+ interface, we have to override the <code>post_person()</code>
+ virtual function in <code>superman_pimpl</code> to call
+ <code>post_superman()</code> and the <code>post_superman()</code>
+ virtual function in <code>batman_pimpl</code> to call
+ <code>post_batman()</code>.</p>
+
+ <p>The following code fragment shows how to connect the parsers together.
+ Notice that for the <code>person</code> element in the <code>supermen_p</code>
+ parser we specify a parser map instead of a specific parser and we pass
+ <code>true</code> as the last argument to the document parser constructor
+ to indicate that we are parsing potentially-polymorphic XML documents:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ // Construct the parser.
+ //
+ xml_schema::string_pimpl string_p;
+ xml_schema::boolean_pimpl boolean_p;
+ xml_schema::unsigned_int_pimpl unsigned_int_p;
+
+ person_pimpl person_p;
+ superman_pimpl superman_p;
+ batman_pimpl batman_p;
+
+ xml_schema::parser_map_impl person_map;
+ supermen_pimpl supermen_p;
+
+ person_p.parsers (string_p);
+ superman_p.parsers (string_p, boolean_p);
+ batman_p.parsers (string_p, boolean_p, unsigned_int_p);
+
+ // Here we are specifying a parser map which containes several
+ // parsers that can be used to parse the person element.
+ //
+ person_map.insert (person_p);
+ person_map.insert (superman_p);
+ person_map.insert (batman_p);
+
+ supermen_p.person_parser (person_map);
+
+ // Parse the XML document. The last argument to the document's
+ // constructor indicates that we are parsing polymorphic XML
+ // documents.
+ //
+ xml_schema::document doc_p (supermen_p, "supermen", true);
+
+ supermen_p.pre ();
+ doc_p.parse (argv[1]);
+ supermen_p.post_supermen ();
+}
+ </pre>
+
+ <p>When polymorphism-aware code is generated, each element's
+ <code>*_parser()</code> function is overloaded to also accept
+ an object of the <code>xml_schema::parser_map</code> type.
+ For example, the <code>supermen_pskel</code> class from the
+ above example looks like this:</p>
+
+ <pre class="c++">
+class supermen_pskel: public xml_schema::parser_complex_content
+{
+public:
+
+ ...
+
+ // Parser construction API.
+ //
+ void
+ parsers (person_pskel&amp;);
+
+ // Individual element parsers.
+ //
+ void
+ person_parser (person_pskel&amp;);
+
+ void
+ person_parser (const xml_schema::parser_map&amp;);
+
+ ...
+};
+ </pre>
+
+ <p>Note that you can specify both the individual (static) parser and
+ the parser map. The individual parser will be used when the static
+ element type and the dynamic type of the object being parsed are
+ the same. This is the case, for example, when there is no
+ <code>xsi:type</code> attribute and the element hasn't been
+ substituted. Because the individual parser for an element is
+ cached and no map lookup is necessary, it makes sense to specify
+ both the individual parser and the parser map when most of the
+ objects being parsed are of the static type and optimal
+ performance is important. The following code fragment shows
+ how to change the above example to set both the individual
+ parser and the parser map:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ ...
+
+ person_map.insert (superman_p);
+ person_map.insert (batman_p);
+
+ supermen_p.person_parser (person_p);
+ supermen_p.person_parser (person_map);
+
+ ...
+}
+ </pre>
+
+
+ <p>The <code>xml_schema::parser_map</code> interface and the
+ <code>xml_schema::parser_map_impl</code> default implementation
+ are presented below:</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_map
+ {
+ public:
+ virtual parser_base*
+ find (const ro_string* type) const = 0;
+ };
+
+ class parser_map_impl: public parser_map
+ {
+ public:
+ void
+ insert (parser_base&amp;);
+
+ virtual parser_base*
+ find (const ro_string* type) const;
+
+ private:
+ parser_map_impl (const parser_map_impl&amp;);
+
+ parser_map_impl&amp;
+ operator= (const parser_map_impl&amp;);
+
+ ...
+ };
+}
+ </pre>
+
+ <p>The <code>type</code> argument in the <code>find()</code> virtual
+ function is the type name and namespace from the xsi:type attribute
+ (the namespace prefix is resolved to the actual XML namespace)
+ or the type of an element from the substitution group in the form
+ <code>"&lt;name>&nbsp;&lt;namespace>"</code> with the space and the
+ namespace part absent if the type does not have a namespace.
+ You can obtain a parser's dynamic type in the same format
+ using the <code>_dynamic_type()</code> function. The static
+ type can be obtained by calling the static <code>_static_type()</code>
+ function, for example <code>person_pskel::_static_type()</code>.
+ Both functions return a C string (<code>const char*</code> or
+ <code>const wchar_t*</code>, depending on the character type
+ used) which is valid for as long as the application is running.
+ The following example shows how we can implement our own parser
+ map using <code>std::map</code>:</p>
+
+
+ <pre class="c++">
+#include &lt;map>
+#include &lt;string>
+
+class parser_map: public xml_schema::parser_map
+{
+public:
+ void
+ insert (xml_schema::parser_base&amp; p)
+ {
+ map_[p._dynamic_type ()] = &amp;p;
+ }
+
+ virtual xml_schema::parser_base*
+ find (const xml_schema::ro_string* type) const
+ {
+ map::const_iterator i = map_.find (type);
+ return i != map_.end () ? i->second : 0;
+ }
+
+private:
+ typedef std::map&lt;std::string, xml_schema::parser_base*> map;
+ map map_;
+};
+ </pre>
+
+ <p>Most of code presented in this section is taken from the
+ <code>polymorphism</code> example which can be found in the
+ <code>cxx/parser/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.
+ Handling of <code>xsi:type</code> and substitution groups when used on
+ root elements requires a number of special actions as shown in
+ the <code>polyroot</code> example.</p>
+
+
+ <!-- Built-in XML Schema Type Parsers -->
+
+
+ <h1><a name="6">6 Built-In XML Schema Type Parsers</a></h1>
+
+ <p>The XSD runtime provides parser implementations for all built-in
+ XML Schema types as summarized in the following table. Declarations
+ for these types are automatically included into each generated
+ header file. As a result you don't need to include any headers
+ to gain access to these parser implementations. Note that some
+ parsers return either <code>std::string</code> or
+ <code>std::wstring</code> depending on the character type selected.</p>
+
+ <!-- border="1" is necessary for html2ps -->
+ <table id="builtin" border="1">
+ <tr>
+ <th>XML Schema type</th>
+ <th>Parser implementation in the <code>xml_schema</code> namespace</th>
+ <th>Parser return type</th>
+ </tr>
+
+ <tr>
+ <th colspan="3">anyType and anySimpleType types</th>
+ </tr>
+ <tr>
+ <td><code>anyType</code></td>
+ <td><code>any_type_pimpl</code></td>
+ <td><code>void</code></td>
+ </tr>
+ <tr>
+ <td><code>anySimpleType</code></td>
+ <td><code>any_simple_type_pimpl</code></td>
+ <td><code>void</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">fixed-length integral types</th>
+ </tr>
+ <!-- 8-bit -->
+ <tr>
+ <td><code>byte</code></td>
+ <td><code>byte_pimpl</code></td>
+ <td><code>signed&nbsp;char</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedByte</code></td>
+ <td><code>unsigned_byte_pimpl</code></td>
+ <td><code>unsigned&nbsp;char</code></td>
+ </tr>
+
+ <!-- 16-bit -->
+ <tr>
+ <td><code>short</code></td>
+ <td><code>short_pimpl</code></td>
+ <td><code>short</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedShort</code></td>
+ <td><code>unsigned_short_pimpl</code></td>
+ <td><code>unsigned&nbsp;short</code></td>
+ </tr>
+
+ <!-- 32-bit -->
+ <tr>
+ <td><code>int</code></td>
+ <td><code>int_pimpl</code></td>
+ <td><code>int</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedInt</code></td>
+ <td><code>unsigned_int_pimpl</code></td>
+ <td><code>unsigned&nbsp;int</code></td>
+ </tr>
+
+ <!-- 64-bit -->
+ <tr>
+ <td><code>long</code></td>
+ <td><code>long_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>unsignedLong</code></td>
+ <td><code>unsigned_long_pimpl</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_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>nonPositiveInteger</code></td>
+ <td><code>non_positive_integer_pimpl</code></td>
+ <td><code>long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>nonNegativeInteger</code></td>
+ <td><code>non_negative_integer_pimpl</code></td>
+ <td><code>unsigned long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>positiveInteger</code></td>
+ <td><code>positive_integer_pimpl</code></td>
+ <td><code>unsigned long&nbsp;long</code></td>
+ </tr>
+ <tr>
+ <td><code>negativeInteger</code></td>
+ <td><code>negative_integer_pimpl</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_pimpl</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_pimpl</code></td>
+ <td><code>float</code></td>
+ </tr>
+ <tr>
+ <td><code>double</code></td>
+ <td><code>double_pimpl</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_pimpl</code></td>
+ <td><code>double</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">string-based types</th>
+ </tr>
+ <tr>
+ <td><code>string</code></td>
+ <td><code>string_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>normalizedString</code></td>
+ <td><code>normalized_string_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>token</code></td>
+ <td><code>token_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>Name</code></td>
+ <td><code>name_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>NMTOKEN</code></td>
+ <td><code>nmtoken_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>NCName</code></td>
+ <td><code>ncname_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <td><code>language</code></td>
+ <td><code>language_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">qualified name</th>
+ </tr>
+ <tr>
+ <td><code>QName</code></td>
+ <td><code>qname_pimpl</code></td>
+ <td><code>xml_schema::qname</code><br/><a href="#6.1">Section 6.1,
+ "<code>QName</code> Parser"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">ID/IDREF types</th>
+ </tr>
+ <tr>
+ <td><code>ID</code></td>
+ <td><code>id_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+ <tr>
+ <td><code>IDREF</code></td>
+ <td><code>idref_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">list types</th>
+ </tr>
+ <tr>
+ <td><code>NMTOKENS</code></td>
+ <td><code>nmtokens_pimpl</code></td>
+ <td><code>xml_schema::string_sequence</code><br/><a href="#6.2">Section
+ 6.2, "<code>NMTOKENS</code> and <code>IDREFS</code> Parsers"</a></td>
+ </tr>
+ <tr>
+ <td><code>IDREFS</code></td>
+ <td><code>idrefs_pimpl</code></td>
+ <td><code>xml_schema::string_sequence</code><br/><a href="#6.2">Section
+ 6.2, "<code>NMTOKENS</code> and <code>IDREFS</code> Parsers"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">URI types</th>
+ </tr>
+ <tr>
+ <td><code>anyURI</code></td>
+ <td><code>uri_pimpl</code></td>
+ <td><code>std::string</code> or <code>std::wstring</code></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">binary types</th>
+ </tr>
+ <tr>
+ <td><code>base64Binary</code></td>
+ <td><code>base64_binary_pimpl</code></td>
+ <td><code>std::[unique|auto]_ptr&lt; xml_schema::buffer></code><br/>
+ <a href="#6.3">Section 6.3, "<code>base64Binary</code> and
+ <code>hexBinary</code> Parsers"</a></td>
+ </tr>
+ <tr>
+ <td><code>hexBinary</code></td>
+ <td><code>hex_binary_pimpl</code></td>
+ <td><code>std::[unique|auto]_ptr&lt; xml_schema::buffer></code><br/>
+ <a href="#6.3">Section 6.3, "<code>base64Binary</code> and
+ <code>hexBinary</code> Parsers"</a></td>
+ </tr>
+
+ <tr>
+ <th colspan="3">date/time types</th>
+ </tr>
+ <tr>
+ <td><code>date</code></td>
+ <td><code>date_pimpl</code></td>
+ <td><code>xml_schema::date</code><br/><a href="#6.5">Section 6.5,
+ "<code>date</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>dateTime</code></td>
+ <td><code>date_time_pimpl</code></td>
+ <td><code>xml_schema::date_time</code><br/><a href="#6.6">Section 6.6,
+ "<code>dateTime</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>duration</code></td>
+ <td><code>duration_pimpl</code></td>
+ <td><code>xml_schema::duration</code><br/><a href="#6.7">Section 6.7,
+ "<code>duration</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gDay</code></td>
+ <td><code>gday_pimpl</code></td>
+ <td><code>xml_schema::gday</code><br/><a href="#6.8">Section 6.8,
+ "<code>gDay</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gMonth</code></td>
+ <td><code>gmonth_pimpl</code></td>
+ <td><code>xml_schema::gmonth</code><br/><a href="#6.9">Section 6.9,
+ "<code>gMonth</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gMonthDay</code></td>
+ <td><code>gmonth_day_pimpl</code></td>
+ <td><code>xml_schema::gmonth_day</code><br/><a href="#6.10">Section 6.10,
+ "<code>gMonthDay</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gYear</code></td>
+ <td><code>gyear_pimpl</code></td>
+ <td><code>xml_schema::gyear</code><br/><a href="#6.11">Section 6.11,
+ "<code>gYear</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>gYearMonth</code></td>
+ <td><code>gyear_month_pimpl</code></td>
+ <td><code>xml_schema::gyear_month</code><br/><a href="#6.12">Section
+ 6.12, "<code>gYearMonth</code> Parser"</a></td>
+ </tr>
+ <tr>
+ <td><code>time</code></td>
+ <td><code>time_pimpl</code></td>
+ <td><code>xml_schema::time</code><br/><a href="#6.13">Section 6.13,
+ "<code>time</code> Parser"</a></td>
+ </tr>
+
+ </table>
+
+ <h2><a name="6.1">6.1 <code>QName</code> Parser</a></h2>
+
+ <p>The return type of the <code>qname_pimpl</code> parser implementation
+ is <code>xml_schema::qname</code> which represents an XML qualified
+ name. Its interface is presented below.
+ Note that the <code>std::string</code> type in the interface becomes
+ <code>std::wstring</code> if the selected character type is
+ <code>wchar_t</code>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class qname
+ {
+ public:
+ explicit
+ qname (const std::string&amp; name);
+ qname (const std::string&amp; prefix, const std::string&amp; name);
+
+ const std::string&amp;
+ prefix () const;
+
+ void
+ prefix (const std::string&amp;);
+
+ const std::string&amp;
+ name () const;
+
+ void
+ name (const std::string&amp;);
+ };
+
+ bool
+ operator== (const qname&amp;, const qname&amp;);
+
+ bool
+ operator!= (const qname&amp;, const qname&amp;);
+}
+ </pre>
+
+
+ <h2><a name="6.2">6.2 <code>NMTOKENS</code> and <code>IDREFS</code> Parsers</a></h2>
+
+ <p>The return type of the <code>nmtokens_pimpl</code> and
+ <code>idrefs_pimpl</code> parser implementations is
+ <code>xml_schema::string_sequence</code> which represents a
+ sequence of strings. Its interface is presented below.
+ Note that the <code>std::string</code> type in the interface becomes
+ <code>std::wstring</code> if the selected character type is
+ <code>wchar_t</code>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class string_sequence: public std::vector&lt;std::string>
+ {
+ public:
+ string_sequence ();
+
+ explicit
+ string_sequence (std::vector&lt;std::string>::size_type n,
+ const std::string&amp; x = std::string ());
+
+ template &lt;typename I>
+ string_sequence (const I&amp; begin, const I&amp; end);
+ };
+
+ bool
+ operator== (const string_sequence&amp;, const string_sequence&amp;);
+
+ bool
+ operator!= (const string_sequence&amp;, const string_sequence&amp;);
+}
+ </pre>
+
+
+ <h2><a name="6.3">6.3 <code>base64Binary</code> and <code>hexBinary</code> Parsers</a></h2>
+
+ <p>The return type of the <code>base64_binary_pimpl</code> and
+ <code>hex_binary_pimpl</code> parser implementations is either
+ <code>std::unique_ptr&lt;xml_schema::buffer></code> (C++11) or
+ <code>std::auto_ptr&lt;xml_schema::buffer></code> (C++98),
+ depending on the C++ standard selected (<code>--std</code> XSD
+ compiler option). The <code>xml_schema::buffer</code> type
+ represents a binary buffer and its interface is presented below.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class buffer
+ {
+ public:
+ typedef std::size_t size_t;
+
+ class bounds {}; // Out of bounds exception.
+
+ public:
+ explicit
+ 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 ();
+ };
+
+ bool
+ operator== (const buffer&amp;, const buffer&amp;);
+
+ bool
+ operator!= (const buffer&amp;, const buffer&amp;);
+}
+ </pre>
+
+ <p>If the <code>assume_ownership</code> argument to the constructor
+ is <code>true</code>, the instance assumes the 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>
+
+
+ <h2><a name="6.4">6.4 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++">
+namespace xml_schema
+{
+ 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="6.5">6.5 <code>date</code> Parser</a></h2>
+
+ <p>The return type of the <code>date_pimpl</code> parser implementation
+ is <code>xml_schema::date</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class date
+ {
+ 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);
+
+ 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="6.6">6.6 <code>dateTime</code> Parser</a></h2>
+
+ <p>The return type of the <code>date_time_pimpl</code> parser implementation
+ is <code>xml_schema::date_time</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class date_time
+ {
+ 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);
+
+ 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="6.7">6.7 <code>duration</code> Parser</a></h2>
+
+ <p>The return type of the <code>duration_pimpl</code> parser implementation
+ is <code>xml_schema::duration</code> 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++">
+namespace xml_schema
+{
+ class duration
+ {
+ public:
+ duration (bool negative,
+ unsigned int years, unsigned int months, unsigned int days,
+ unsigned int hours, unsigned int minutes, double seconds);
+
+ 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="6.8">6.8 <code>gDay</code> Parser</a></h2>
+
+ <p>The return type of the <code>gday_pimpl</code> parser implementation
+ is <code>xml_schema::gday</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gday
+ {
+ public:
+ explicit
+ gday (unsigned short day);
+ gday (unsigned short day, short zone_hours, short zone_minutes);
+
+ 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="6.9">6.9 <code>gMonth</code> Parser</a></h2>
+
+ <p>The return type of the <code>gmonth_pimpl</code> parser implementation
+ is <code>xml_schema::gmonth</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gmonth
+ {
+ public:
+ explicit
+ gmonth (unsigned short month);
+ gmonth (unsigned short month, short zone_hours, short zone_minutes);
+
+ 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="6.10">6.10 <code>gMonthDay</code> Parser</a></h2>
+
+ <p>The return type of the <code>gmonth_day_pimpl</code> parser implementation
+ is <code>xml_schema::gmonth_day</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gmonth_day
+ {
+ public:
+ gmonth_day (unsigned short month, unsigned short day);
+ gmonth_day (unsigned short month, unsigned short day,
+ short zone_hours, short zone_minutes);
+
+ 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="6.11">6.11 <code>gYear</code> Parser</a></h2>
+
+ <p>The return type of the <code>gyear_pimpl</code> parser implementation
+ is <code>xml_schema::gyear</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gyear
+ {
+ public:
+ explicit
+ gyear (int year);
+ gyear (int year, short zone_hours, short zone_minutes);
+
+ 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="6.12">6.12 <code>gYearMonth</code> Parser</a></h2>
+
+ <p>The return type of the <code>gyear_month_pimpl</code> parser implementation
+ is <code>xml_schema::gyear_month</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class gyear_month
+ {
+ public:
+ gyear_month (int year, unsigned short month);
+ gyear_month (int year, unsigned short month,
+ short zone_hours, short zone_minutes);
+
+ 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="6.13">6.13 <code>time</code> Parser</a></h2>
+
+ <p>The return type of the <code>time_pimpl</code> parser implementation
+ is <code>xml_schema::time</code> 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="#6.4">Section 6.4, "Time Zone
+ Representation"</a>.</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class time
+ {
+ 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);
+
+ 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>
+
+
+ <!-- Error Handling -->
+
+
+ <h1><a name="7">7 Document Parser and Error Handling</a></h1>
+
+ <p>In this chapter we will discuss the <code>xml_schema::document</code>
+ type as well as the error handling mechanisms provided by the mapping
+ in more detail. As mentioned in <a href="#3.4">Section 3.4,
+ "Connecting the Parsers Together"</a>, the interface of
+ <code>xml_schema::document</code> depends on the underlying XML
+ parser selected (<a href="#5.3">Section 5.3, "Underlying XML
+ Parser"</a>). The following sections describe the
+ <code>document</code> type interface for Xerces-C++ and
+ Expat as underlying parsers.</p>
+
+ <h2><a name="7.1">7.1 Xerces-C++ Document Parser</a></h2>
+
+ <p>When Xerces-C++ is used as the underlying XML parser, the
+ <code>document</code> type has the following interface. Note that
+ if the character type is <code>wchar_t</code>, then the string type
+ in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_base;
+ class error_handler;
+
+ class flags
+ {
+ public:
+ // Do not validate XML documents with the Xerces-C++ validator.
+ //
+ static const unsigned long dont_validate;
+
+ // Do not initialize the Xerces-C++ runtime.
+ //
+ static const unsigned long dont_initialize;
+
+ // Disable handling of subsequent imports for the same namespace
+ // in Xerces-C++ 3.1.0 and later.
+ //
+ static const unsigned long no_multiple_imports;
+ };
+
+ class properties
+ {
+ public:
+ // Add a location for a schema with a target namespace.
+ //
+ void
+ schema_location (const std::string&amp; namespace_,
+ const std::string&amp; location);
+
+ // Add a location for a schema without a target namespace.
+ //
+ void
+ no_namespace_schema_location (const std::string&amp; location);
+ };
+
+ class document
+ {
+ public:
+ document (parser_base&amp; root,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (parser_base&amp; root,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ public:
+ // Parse URI or a local file.
+ //
+ void
+ parse (const std::string&amp; uri,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file with a user-provided error_handler
+ // object.
+ //
+ void
+ parse (const std::string&amp; uri,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file with a user-provided ErrorHandler
+ // object. Note that you must initialize the Xerces-C++ runtime
+ // before calling this function.
+ //
+ void
+ parse (const std::string&amp; uri,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse URI or a local file using a user-provided SAX2XMLReader
+ // object. Note that you must initialize the Xerces-C++ runtime
+ // before calling this function.
+ //
+ void
+ parse (const std::string&amp; uri,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream.
+ //
+ void
+ parse (std::istream&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a user-provided error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a user-provided ErrorHandler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream using a user-provided SAX2XMLReader object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream with a system id.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id and a user-provided
+ // ErrorHandler object. Note that you must initialize the
+ // Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with a system id using a user-provided
+ // SAX2XMLReader object. Note that you must initialize the
+ // Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse std::istream with system and public ids.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids and a user-provided
+ // ErrorHandler object. Note that you must initialize the Xerces-C++
+ // runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse std::istream with system and public ids using a user-
+ // provided SAX2XMLReader object. Note that you must initialize
+ // the Xerces-C++ runtime before calling this function.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ public:
+ // Parse InputSource. Note that you must initialize the Xerces-C++
+ // runtime before calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource with a user-provided error_handler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ error_handler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource with a user-provided ErrorHandler object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ xercesc::ErrorHandler&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+
+ // Parse InputSource using a user-provided SAX2XMLReader object.
+ // Note that you must initialize the Xerces-C++ runtime before
+ // calling this function.
+ //
+ void
+ parse (const xercesc::InputSource&amp;,
+ xercesc::SAX2XMLReader&amp;,
+ flags = 0,
+ const properties&amp; = properties ());
+ };
+}
+ </pre>
+
+ <p>The <code>document</code> class is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element. The <code>parser_base</code>
+ class is the base type for all parser skeletons. The second and
+ third arguments to the <code>document</code>'s constructors are
+ the root element's name and namespace. The last argument,
+ <code>polymorphic</code>, specifies whether the XML documents
+ being parsed use polymorphism. For more information on support
+ for XML Schema polymorphism in the C++/Parser mapping refer
+ to <a href="#5.5">Section 5.5, "Support for Polymorphism"</a>.</p>
+
+ <p>The rest of the <code>document</code> interface consists of overloaded
+ <code>parse()</code> functions. The last two arguments in each of these
+ functions are <code>flags</code> and <code>properties</code>. The
+ <code>flags</code> argument allows you to modify the default behavior
+ of the parsing functions. The <code>properties</code> argument allows
+ you to override the schema location attributes specified in XML
+ documents. Note that the schema location paths are relative to an
+ XML document unless they are complete URIs. For example if you want
+ to use a local schema file then you will need to use a URI in the
+ form <code>file:///absolute/path/to/your/schema</code>.</p>
+
+ <p>A number of overloaded <code>parse()</code> functions have the
+ <code>system_id</code> and <code>public_id</code> arguments. The
+ system id is a <em>system</em> identifier of the resources being
+ parsed (for example, URI or a full file path). The public id is a
+ <em>public</em> identifier of the resource (for example, an
+ application-specific name or a relative file path). The system id
+ is used to resolve relative paths (for example, schema paths). In
+ diagnostics messages the public id is used if it is available.
+ Otherwise the system id is used.</p>
+
+ <p>The error handling mechanisms employed by the <code>document</code>
+ parser are described in <a href="#7.3">Section 7.3, "Error
+ Handling"</a>.</p>
+
+ <h2><a name="7.2">7.2 Expat Document Parser</a></h2>
+
+ <p>When Expat is used as the underlying XML parser, the
+ <code>document</code> type has the following interface. Note that
+ if the character type is <code>wchar_t</code>, then the string type
+ in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class parser_base;
+ class error_handler;
+
+ class document
+ {
+ public:
+ document (parser_base&amp;,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ document (parser_base&amp;,
+ const std::string&amp; root_element_namespace,
+ const std::string&amp; root_element_name,
+ bool polymorphic = false);
+
+ public:
+ // Parse a local file. The file is accessed with std::ifstream
+ // in binary mode. The std::ios_base::failure exception is used
+ // to report io errors (badbit and failbit).
+ void
+ parse (const std::string&amp; file);
+
+ // Parse a local file with a user-provided error_handler
+ // object. The file is accessed with std::ifstream in binary
+ // mode. The std::ios_base::failure exception is used to report
+ // io errors (badbit and failbit).
+ //
+ void
+ parse (const std::string&amp; file, error_handler&amp;);
+
+ public:
+ // Parse std::istream.
+ //
+ void
+ parse (std::istream&amp;);
+
+ // Parse std::istream with a user-provided error_handler object.
+ //
+ void
+ parse (std::istream&amp;, error_handler&amp;);
+
+ // Parse std::istream with a system id.
+ //
+ void
+ parse (std::istream&amp;, const std::string&amp; system_id);
+
+ // Parse std::istream with a system id and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ error_handler&amp;);
+
+ // Parse std::istream with system and public ids.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id);
+
+ // Parse std::istream with system and public ids and a user-provided
+ // error_handler object.
+ //
+ void
+ parse (std::istream&amp;,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+
+ public:
+ // Parse a chunk of input. You can call these functions multiple
+ // times with the last call having the last argument true.
+ //
+ void
+ parse (const void* data, std::size_t size, bool last);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ error_handler&amp;);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ error_handler&amp;);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id);
+
+ void
+ parse (const void* data, std::size_t size, bool last,
+ const std::string&amp; system_id,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+
+ public:
+ // Low-level Expat-specific parsing API.
+ //
+ void
+ parse_begin (XML_Parser);
+
+ void
+ parse_begin (XML_Parser, const std::string&amp; public_id);
+
+ void
+ parse_begin (XML_Parser, error_handler&amp;);
+
+ void
+ parse_begin (XML_Parser,
+ const std::string&amp; public_id,
+ error_handler&amp;);
+ void
+ parse_end ();
+ };
+}
+ </pre>
+
+ <p>The <code>document</code> class is a root parser for
+ the vocabulary. The first argument to its constructors is the
+ parser for the type of the root element. The <code>parser_base</code>
+ class is the base type for all parser skeletons. The second and
+ third arguments to the <code>document</code>'s constructors are
+ the root element's name and namespace. The last argument,
+ <code>polymorphic</code>, specifies whether the XML documents
+ being parsed use polymorphism. For more information on support
+ for XML Schema polymorphism in the C++/Parser mapping refer
+ to <a href="#5.5">Section 5.5, "Support for Polymorphism"</a>.</p>
+
+ <p>A number of overloaded <code>parse()</code> functions have the
+ <code>system_id</code> and <code>public_id</code> arguments. The
+ system id is a <em>system</em> identifier of the resources being
+ parsed (for example, URI or a full file path). The public id is a
+ <em>public</em> identifier of the resource (for example, an
+ application-specific name or a relative file path). The system id
+ is used to resolve relative paths. In diagnostics messages the
+ public id is used if it is available. Otherwise the system id
+ is used.</p>
+
+ <p>The <code>parse_begin()</code> and <code>parse_end()</code> functions
+ present a low-level, Expat-specific parsing API for maximum control.
+ A typical use-case would look like this (pseudo-code):</p>
+
+ <pre class="c++">
+xxx_pimpl root_p;
+document doc_p (root_p, "root");
+
+root_p.pre ();
+doc_p.parse_begin (xml_parser, "file.xml");
+
+while (more_data_to_parse)
+{
+ // Call XML_Parse or XML_ParseBuffer.
+
+ if (status == XML_STATUS_ERROR)
+ break;
+}
+
+// Call parse_end even in case of an error to translate
+// XML and Schema errors to exceptions or error_handler
+// calls.
+//
+doc.parse_end ();
+result_type result (root_p.post_xxx ());
+ </pre>
+
+ <p>Note that if your vocabulary uses XML namespaces, the
+ <code>XML_ParserCreateNS()</code> functions should be used to create
+ the XML parser. Space (<code>XML_Char (' ')</code>) should be used
+ as a separator (the second argument to <code>XML_ParserCreateNS()</code>).
+ </p>
+
+ <p>The error handling mechanisms employed by the <code>document</code>
+ parser are described in <a href="#7.3">Section 7.3, "Error
+ Handling"</a>.</p>
+
+
+ <h2><a name="7.3">7.3 Error Handling</a></h2>
+
+ <p>There are three categories of errors that can result from running
+ a parser on an XML document: System, XML, and Application.
+ The System category contains memory allocation and file/stream
+ operation errors. The XML category covers XML parsing and
+ well-formedness checking as well as XML Schema validation errors.
+ Finally, the Application category is for application logic errors
+ that you may want to propagate from parser implementations to the
+ caller of the parser.
+ </p>
+
+ <p>The System errors are mapped to the standard exceptions. The
+ out of memory condition is indicated by throwing an instance
+ of <code>std::bad_alloc</code>. The stream operation errors
+ are reported either by throwing an instance of
+ <code>std::ios_base::failure</code> if exceptions are enabled
+ or by setting the stream state.</p>
+
+ <p>Note that if you are parsing <code>std::istream</code> on
+ which exceptions are not enabled, then you will need to
+ check the stream state before calling the <code>post()</code>
+ callback, as shown in the following example:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ ...
+
+ std::ifstream ifs (argv[1]);
+
+ if (ifs.fail ())
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": unable to open" &lt;&lt; endl;
+ return 1;
+ }
+
+ root_p.pre ();
+ doc_p.parse (ifs);
+
+ if (ifs.fail ())
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": io failure" &lt;&lt; endl;
+ return 1;
+ }
+
+ result_type result (root_p.post_xxx ());
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions
+ as shown below:</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ ...
+
+ std::ifstream ifs;
+ ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
+ ifs.open (argv[1]);
+
+ root_p.pre ();
+ doc_p.parse (ifs);
+ result_type result (root_p.post_xxx ());
+ }
+ catch (const std::ifstream::failure&amp;)
+ {
+ cerr &lt;&lt; argv[1] &lt;&lt; ": unable to open or io failure" &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+
+ <p>For reporting application errors from parsing callbacks, you
+ can throw any exceptions of your choice. They are propagated to
+ the caller of the parser without any alterations.</p>
+
+ <p>The XML errors can be reported either by throwing the
+ <code>xml_schema::parsing</code> exception or by a callback
+ to the <code>xml_schema::error_handler</code> object (and
+ <code>xercesc::ErrorHandler</code> object in case of Xerces-C++).</p>
+
+ <p>The <code>xml_schema::parsing</code> exception contains
+ a list of warnings and errors that were accumulated during
+ parsing. Note that this exception is thrown only if there
+ was an error. This makes it impossible to obtain warnings
+ from an otherwise successful parsing using this mechanism.
+ The following listing shows the definition of
+ <code>xml_schema::parsing</code> exception. Note that if the
+ character type is <code>wchar_t</code>, then the string type
+ and output stream type in the definition become
+ <code>std::wstring</code> and <code>std::wostream</code>,
+ respectively (see <a href="#5.2">Section 5.2, "Character Type
+ and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class exception: public std::exception
+ {
+ protected:
+ virtual void
+ print (std::ostream&amp;) const = 0;
+ };
+
+ inline std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp; os, const exception&amp; e)
+ {
+ e.print (os);
+ return os;
+ }
+
+
+ class severity
+ {
+ public:
+ enum value
+ {
+ warning,
+ error
+ };
+ };
+
+
+ class error
+ {
+ public:
+ error (xml_schema::severity,
+ const std::string&amp; id,
+ unsigned long line,
+ unsigned long column,
+ const std::string&amp; message);
+
+ xml_schema::severity
+ severity () const;
+
+ const std::string&amp;
+ id () const;
+
+ unsigned long
+ line () const;
+
+ unsigned long
+ column () const;
+
+ const std::string&amp;
+ message () const;
+ };
+
+ std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp;, const error&amp;);
+
+
+ class diagnostics: public std::vector&lt;error>
+ {
+ };
+
+ std::ostream&amp;
+ operator&lt;&lt; (std::ostream&amp;, const diagnostics&amp;);
+
+
+ class parsing: public exception
+ {
+ public:
+ parsing ();
+ parsing (const xml_schema::diagnostics&amp;);
+
+ const xml_schema::diagnostics&amp;
+ diagnostics () const;
+
+ virtual const char*
+ what () const throw ();
+
+ protected:
+ virtual void
+ print (std::ostream&amp;) const;
+ };
+}
+ </pre>
+
+ <p>The following example shows how we can catch and print this
+ exception. The code will print diagnostics messages one per line
+ in case of an error.</p>
+
+ <pre class="c++">
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ // Parse.
+ }
+ catch (const xml_schema::parsing&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>With the <code>error_handler</code> approach the diagnostics
+ messages are delivered as parsing progresses. The following
+ listing presents the definition of the <code>error_handler</code>
+ interface. Note that if the character type is <code>wchar_t</code>,
+ then the string type in the interface becomes <code>std::wstring</code>
+ (see <a href="#5.2">Section 5.2, "Character Type and Encoding"</a>).</p>
+
+ <pre class="c++">
+namespace xml_schema
+{
+ class error_handler
+ {
+ public:
+ class severity
+ {
+ public:
+ enum value
+ {
+ warning,
+ error,
+ fatal
+ };
+ };
+
+ virtual bool
+ handle (const std::string&amp; id,
+ unsigned long line,
+ unsigned long column,
+ severity,
+ const std::string&amp; message) = 0;
+ };
+}
+ </pre>
+
+ <p>The return value of the <code>handle()</code> function indicates whether
+ parsing should continue if possible. The error with the fatal severity
+ level terminates the parsing process regardless of the returned value.
+ At the end of the parsing process with an error that was reported via
+ the <code>error_handler</code> object, an empty
+ <code>xml_schema::parsing</code> exception is thrown to indicate
+ the failure to the caller. You can alter this behavior by throwing
+ your own exception from the <code>handle()</code> function.</p>
+
+
+ <!-- Appendix A -->
+
+
+ <h1><a name="A">Appendix A &mdash; Supported XML Schema Constructs</a></h1>
+
+ <p>The C++/Parser mapping supports validation of the following W3C XML
+ Schema constructs in the generated code.</p>
+
+ <!-- border="1" is necessary for html2ps -->
+ <table id="features" border="1">
+ <tr><th>Construct</th><th>Notes</th></tr>
+ <tr><th colspan="2">Structure</th></tr>
+
+ <tr><td>element</td><td></td></tr>
+ <tr><td>attribute</td><td></td></tr>
+
+ <tr><td>any</td><td></td></tr>
+ <tr><td>anyAttribute</td><td></td></tr>
+
+ <tr><td>all</td><td></td></tr>
+ <tr><td>sequence</td><td></td></tr>
+ <tr><td>choice</td><td></td></tr>
+
+ <tr><td>complex type, empty content</td><td></td></tr>
+ <tr><td>complex type, mixed content</td><td></td></tr>
+ <tr><td>complex type, simple content extension</td><td></td></tr>
+ <tr><td>complex type, simple content restriction</td>
+ <td>Simple type facets are not validated.</td></tr>
+ <tr><td>complex type, complex content extension</td><td></td></tr>
+ <tr><td>complex type, complex content restriction</td><td></td></tr>
+
+ <tr><td>list</td><td></td></tr>
+
+ <tr><th colspan="2">Datatypes</th></tr>
+
+ <tr><td>byte</td><td></td></tr>
+ <tr><td>unsignedByte</td><td></td></tr>
+ <tr><td>short</td><td></td></tr>
+ <tr><td>unsignedShort</td><td></td></tr>
+ <tr><td>int</td><td></td></tr>
+ <tr><td>unsignedInt</td><td></td></tr>
+ <tr><td>long</td><td></td></tr>
+ <tr><td>unsignedLong</td><td></td></tr>
+ <tr><td>integer</td><td></td></tr>
+ <tr><td>nonPositiveInteger</td><td></td></tr>
+ <tr><td>nonNegativeInteger</td><td></td></tr>
+ <tr><td>positiveInteger</td><td></td></tr>
+ <tr><td>negativeInteger</td><td></td></tr>
+
+ <tr><td>boolean</td><td></td></tr>
+
+ <tr><td>float</td><td></td></tr>
+ <tr><td>double</td><td></td></tr>
+ <tr><td>decimal</td><td></td></tr>
+
+ <tr><td>string</td><td></td></tr>
+ <tr><td>normalizedString</td><td></td></tr>
+ <tr><td>token</td><td></td></tr>
+ <tr><td>Name</td><td></td></tr>
+ <tr><td>NMTOKEN</td><td></td></tr>
+ <tr><td>NCName</td><td></td></tr>
+ <tr><td>language</td><td></td></tr>
+ <tr><td>anyURI</td><td></td></tr>
+
+ <tr><td>ID</td><td>Identity constraint is not enforced.</td></tr>
+ <tr><td>IDREF</td><td>Identity constraint is not enforced.</td></tr>
+
+ <tr><td>NMTOKENS</td><td></td></tr>
+ <tr><td>IDREFS</td><td>Identity constraint is not enforced.</td></tr>
+
+ <tr><td>QName</td><td></td></tr>
+
+ <tr><td>base64Binary</td><td></td></tr>
+ <tr><td>hexBinary</td><td></td></tr>
+
+ <tr><td>date</td><td></td></tr>
+ <tr><td>dateTime</td><td></td></tr>
+ <tr><td>duration</td><td></td></tr>
+ <tr><td>gDay</td><td></td></tr>
+ <tr><td>gMonth</td><td></td></tr>
+ <tr><td>gMonthDay</td><td></td></tr>
+ <tr><td>gYear</td><td></td></tr>
+ <tr><td>gYearMonth</td><td></td></tr>
+ <tr><td>time</td><td></td></tr>
+ </table>
+
+
+ </div>
+</div>
+
+</body>
+</html>
diff --git a/doc/cxx/tree/guide/guide.html2ps.in b/doc/cxx/tree/guide/guide.html2ps.in
new file mode 100644
index 0000000..461ffde
--- /dev/null
+++ b/doc/cxx/tree/guide/guide.html2ps.in
@@ -0,0 +1,65 @@
+@@html2ps {
+ option {
+ toc: hb;
+ colour: 1;
+ hyphenate: 1;
+ titlepage: 1;
+ }
+
+ datefmt: "%B %Y";
+
+ titlepage {
+ content: "
+<div align=center>
+ <h1><big>C++/Tree Mapping</big></h1>
+ <h1><big>Getting Started Guide</big></h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+</div>
+ <p>Copyright &#169; @copyright@.</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/guide/index.xhtml'>XHTML</a>,
+ <a href='https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-parser-guide.pdf'>PDF</a>, and
+ <a href='https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-parser-guide.ps'>PostScript</a>.</p>";
+ }
+
+ toc {
+ indent: 2em;
+ }
+
+ header {
+ odd-right: $H;
+ even-left: $H;
+ }
+
+ footer {
+ odd-left: $D;
+ odd-center: $T;
+ odd-right: $N;
+
+ even-left: $N;
+ even-center: $T;
+ even-right: $D;
+ }
+}
+
+body {
+ font-size: 12pt;
+ text-align: justify;
+}
+
+pre {
+ font-size: 10pt;
+}
diff --git a/doc/cxx/tree/guide/index.xhtml b/doc/cxx/tree/guide/index.xhtml
new file mode 100644
index 0000000..fdaaa45
--- /dev/null
+++ b/doc/cxx/tree/guide/index.xhtml
@@ -0,0 +1,2736 @@
+<?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 Getting Started Guide</title>
+
+ <meta name="copyright" content="&#169; 2005-2023 Code Synthesis"/>
+ <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,parsing,serialization,validation"/>
+ <meta name="description" content="C++/Tree Mapping Getting Started Guide"/>
+
+ <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%;
+ line-height: 1.2em;
+ }
+
+ h2 {
+ font-weight : bold;
+ font-size : 150%;
+
+ padding-top : 0.8em;
+ }
+
+ h3 {
+ font-size : 140%;
+ 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;
+ }
+
+ #titlepage #first-title {
+ padding: 1em 0 0.4em 0;
+ }
+
+ #titlepage #second-title {
+ padding: 0.4em 0 2em 0;
+ }
+
+ /* Lists */
+ ul.list li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+ div.img {
+ text-align: center;
+ padding: 2em 0 2em 0;
+ }
+
+ /* */
+ dl dt {
+ padding : 0.8em 0 0 0;
+ }
+
+ /* 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;
+ }
+
+ /* 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 class="title" id="first-title">C++/Tree Mapping</div>
+ <div class="title" id="second-title">Getting Started Guide</div>
+
+ <p>Copyright &#169; 2005-2023 Code Synthesis.</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/guide/index.xhtml">XHTML</a>,
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-tree-guide.pdf">PDF</a>, and
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-tree-guide.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>
+ <table class="toc">
+ <tr><th>1.1</th><td><a href="#1.1">Mapping Overview</a></td></tr>
+ <tr><th>1.2</th><td><a href="#1.2">Benefits</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>2</th><td><a href="#2">Hello World Example</a>
+ <table class="toc">
+ <tr><th>2.1</th><td><a href="#2.1">Writing XML Document and Schema</a></td></tr>
+ <tr><th>2.2</th><td><a href="#2.2">Translating Schema to C++</a></td></tr>
+ <tr><th>2.3</th><td><a href="#2.3">Implementing Application Logic</a></td></tr>
+ <tr><th>2.4</th><td><a href="#2.4">Compiling and Running</a></td></tr>
+ <tr><th>2.5</th><td><a href="#2.5">Adding Serialization</a></td></tr>
+ <tr><th>2.6</th><td><a href="#2.6">Selecting Naming Convention</a></td></tr>
+ <tr><th>2.7</th><td><a href="#2.7">Generating Documentation</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>3</th><td><a href="#3">Overall Mapping Configuration</a>
+ <table class="toc">
+ <tr><th>3.1</th><td><a href="#3.1">C++ Standard</a></td></tr>
+ <tr><th>3.2</th><td><a href="#3.2">Character Type and Encoding</a></td></tr>
+ <tr><th>3.3</th><td><a href="#3.3">Support for Polymorphism </a></td></tr>
+ <tr><th>3.4</th><td><a href="#3.4">Namespace Mapping</a></td></tr>
+ <tr><th>3.5</th><td><a href="#3.5">Thread Safety</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>4</th><td><a href="#4">Working with Object Models</a>
+ <table class="toc">
+ <tr><th>4.1</th><td><a href="#4.1">Attribute and Element Cardinalities</a></td></tr>
+ <tr><th>4.2</th><td><a href="#4.2">Accessing the Object Model</a></td></tr>
+ <tr><th>4.3</th><td><a href="#4.3">Modifying the Object Model</a></td></tr>
+ <tr><th>4.4</th><td><a href="#4.4">Creating the Object Model from Scratch</a></td></tr>
+ <tr><th>4.5</th><td><a href="#4.5">Mapping for the Built-in XML Schema Types</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>5</th><td><a href="#5">Parsing</a>
+ <table class="toc">
+ <tr><th>5.1</th><td><a href="#5.1">XML Schema Validation and Searching</a></td></tr>
+ <tr><th>5.2</th><td><a href="#5.2">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>6</th><td><a href="#6">Serialization</a>
+ <table class="toc">
+ <tr><th>6.1</th><td><a href="#6.1">Namespace and Schema Information</a></td></tr>
+ <tr><th>6.2</th><td><a href="#6.2">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ </table>
+ </div>
+
+ <h1><a name="0">Preface</a></h1>
+
+ <h2><a name="0.1">About This Document</a></h2>
+
+ <p>The goal of this document is to provide you with an understanding of
+ the C++/Tree programming model and allow you to efficiently evaluate
+ XSD against your project's technical requirements. As such, this
+ document is intended for C++ developers and software architects
+ who are looking for an XML processing solution. For a more in-depth
+ description of the C++/Tree mapping refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/">C++/Tree
+ Mapping User Manual</a>.</p>
+
+ <p>Prior experience with XML and C++ is required to understand this
+ document. Basic understanding of XML Schema is advantageous but
+ not expected or required.
+ </p>
+
+
+ <h2><a name="0.2">More Information</a></h2>
+
+ <p>Beyond this guide, 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/manual/">C++/Tree
+ Mapping User Manual</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</li>
+
+ <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a>
+ mailing list is the place to ask technical questions about XSD and the C++/Parser mapping.
+ Furthermore, the <a href="https://www.codesynthesis.com/pipermail/xsd-users/">archives</a>
+ may already have answers to some of your questions.</li>
+ </ul>
+
+ <!-- Introduction -->
+
+ <h1><a name="1">1 Introduction</a></h1>
+
+ <p>Welcome to CodeSynthesis XSD and the C++/Tree mapping. XSD is a
+ cross-platform W3C XML Schema to C++ data binding compiler. 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.
+ </p>
+
+ <h2><a name="1.1">1.1 Mapping Overview</a></h2>
+
+ <p>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. The core of the mapping consists of C++
+ classes that constitute the object model and are derived from
+ types defined in XML Schema as well as XML parsing and
+ serialization code.</p>
+
+ <p>Besides the core features, C++/Tree provide a number of additional
+ mapping elements that can be useful in some applications. These
+ include serialization and extraction to/from formats others than
+ XML, such as unstructured text (useful for debugging) and binary
+ representations such as XDR and CDR for high-speed data processing
+ as well as automatic documentation generation. The C++/Tree mapping
+ also provides a wide range of mechanisms for controlling and
+ customizing the generated code.</p>
+
+ <p>A typical application that uses C++/Tree for XML processing usually
+ performs the following three steps: it first reads (parses) an XML
+ document to an in-memory object model, it then performs some useful
+ computations on that object model which may involve modification
+ of the model, and finally it may write (serialize) the modified
+ object model back to XML.</p>
+
+ <p>The next chapter presents a simple application that performs these
+ three steps. The following chapters show how to use the C++/Tree
+ mapping in more detail.</p>
+
+ <h2><a name="1.2">1.2 Benefits</a></h2>
+
+ <p>Traditional XML access APIs such as Document Object Model (DOM)
+ or Simple API for XML (SAX) have a number of drawbacks that
+ make them less suitable for creating robust and maintainable
+ XML processing applications. These drawbacks include:
+ </p>
+
+ <ul class="list">
+ <li>Generic representation of XML in terms of elements, attributes,
+ and text forces an application developer to write a substantial
+ amount of bridging code that identifies and transforms pieces
+ of information encoded in XML to a representation more suitable
+ for consumption by the application logic.</li>
+
+ <li>String-based flow control defers error detection to runtime.
+ It also reduces code readability and maintainability.</li>
+
+ <li>Lack of type safety because the data is represented as text.</li>
+
+ <li>Resulting applications are hard to debug, change, and
+ maintain.</li>
+ </ul>
+
+ <p>In contrast, statically-typed, vocabulary-specific object model
+ produced by the C++/Tree mapping allows you to operate in your
+ domain terms instead of the generic elements, attributes, and
+ text. Static typing helps catch errors at compile-time rather
+ than at run-time. Automatic code generation frees you for more
+ interesting tasks (such as doing something useful with the
+ information stored in the XML documents) and minimizes the
+ effort needed to adapt your applications to changes in the
+ document structure. To summarize, the C++/Tree object model has
+ the following key advantages over generic XML access APIs:</p>
+
+ <ul class="list">
+ <li><b>Ease of use.</b> The generated code hides all the complexity
+ associated with parsing and serializing XML. This includes navigating
+ the structure and converting between the text representation and
+ data types suitable for manipulation by the application
+ logic.</li>
+
+ <li><b>Natural representation.</b> The object representation allows
+ you to access the XML data using your domain vocabulary instead
+ of generic elements, attributes, and text.</li>
+
+ <li><b>Concise code.</b> With the object representation the
+ application implementation is simpler and thus easier
+ to read and understand.</li>
+
+ <li><b>Safety.</b> The generated object model is statically
+ typed and uses functions instead of strings to access the
+ information. This helps catch programming errors at compile-time
+ rather than at runtime.</li>
+
+ <li><b>Maintainability.</b> Automatic code generation minimizes the
+ effort needed to adapt the application to changes in the
+ document structure. With static typing, the C++ compiler
+ can pin-point the places in the client code that need to be
+ changed.</li>
+
+ <li><b>Compatibility.</b> Sequences of elements are represented in
+ the object model as containers conforming to the standard C++
+ sequence requirements. This makes it possible to use standard
+ C++ algorithms on the object representation and frees you from
+ learning yet another container interface, as is the case with
+ DOM.</li>
+
+ <li><b>Efficiency.</b> If the application makes repetitive use
+ of the data extracted from XML, then the C++/Tree object model
+ is more efficient because the navigation is performed using
+ function calls rather than string comparisons and the XML
+ data is extracted only once. Furthermore, the runtime memory
+ usage is reduced due to more efficient data storage
+ (for instance, storing numeric data as integers instead of
+ strings) as well as the static knowledge of cardinality
+ constraints.</li>
+ </ul>
+
+
+ <!-- Hello World Parser -->
+
+
+ <h1><a name="2">2 Hello World Example</a></h1>
+
+ <p>In this chapter we will examine how to parse, access, modify, and
+ serialize a very simple XML document using the XSD-generated
+ C++/Tree object model. The code presented in this chapter is
+ based on the <code>hello</code> example which can be found in
+ the <code>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.</p>
+
+ <h2><a name="2.1">2.1 Writing XML Document and Schema</a></h2>
+
+ <p>First, we need to get an idea about the structure
+ of the XML documents we are going to process. Our
+ <code>hello.xml</code>, for example, could look like this:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello>
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>Then we can write a description of the above XML in the
+ XML Schema language and save it into <code>hello.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="greeting" type="xs:string"/>
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello_t"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Even if you are not familiar with XML Schema, it
+ should be easy to connect declarations in <code>hello.xsd</code>
+ to elements in <code>hello.xml</code>. The <code>hello_t</code> type
+ is defined as a sequence of the nested <code>greeting</code> and
+ <code>name</code> elements. Note that the term sequence in XML
+ Schema means that elements should appear in a particular order
+ as opposed to appearing multiple times. The <code>name</code>
+ element has its <code>maxOccurs</code> property set to
+ <code>unbounded</code> which means it can appear multiple times
+ in an XML document. Finally, the globally-defined <code>hello</code>
+ element prescribes the root element for our vocabulary. For an
+ easily-approachable introduction to XML Schema refer to
+ <a href="http://www.w3.org/TR/xmlschema-0/">XML Schema Part 0:
+ Primer</a>.</p>
+
+ <p>The above schema is a specification of our XML vocabulary; it tells
+ everybody what valid documents of our XML-based language should look
+ like. We can also update our <code>hello.xml</code> to include the
+ information about the schema so that XML parsers can validate
+ our document:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+
+ <p>The next step is to compile the schema to generate the object
+ model and parsing functions.</p>
+
+ <h2><a name="2.2">2.2 Translating Schema to C++</a></h2>
+
+ <p>Now we are ready to translate our <code>hello.xsd</code> to C++.
+ To do this we invoke the XSD compiler from a terminal (UNIX) or
+ a command prompt (Windows):
+ </p>
+
+ <pre class="terminal">
+$ xsd cxx-tree hello.xsd
+ </pre>
+
+ <p>The XSD compiler produces two C++ files: <code>hello.hxx</code> and
+ <code>hello.cxx</code>. The following code fragment is taken from
+ <code>hello.hxx</code>; it should give you an idea about what gets
+ generated:
+ </p>
+
+ <pre class="c++">
+class hello_t
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::string greeting_type;
+
+ const greeting_type&amp;
+ greeting () const;
+
+ greeting_type&amp;
+ greeting ();
+
+ void
+ greeting (const greeting_type&amp; x);
+
+ // name
+ //
+ typedef xml_schema::string name_type;
+ typedef xsd::sequence&lt;name_type> name_sequence;
+ typedef name_sequence::iterator name_iterator;
+ typedef name_sequence::const_iterator name_const_iterator;
+
+ const name_sequence&amp;
+ name () const;
+
+ name_sequence&amp;
+ name ();
+
+ void
+ name (const name_sequence&amp; s);
+
+ // Constructor.
+ //
+ hello_t (const greeting_type&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;hello_t>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>The <code>hello_t</code> C++ class corresponds to the
+ <code>hello_t</code> XML Schema type. For each element
+ in this type a set of C++ type definitions as well as
+ accessor and modifier functions are generated inside the
+ <code>hello_t</code> class. Note that the type definitions
+ and member functions for the <code>greeting</code> and
+ <code>name</code> elements are different because of the
+ cardinality differences between these two elements
+ (<code>greeting</code> is a required single element and
+ <code>name</code> is a sequence of elements).</p>
+
+ <p>The <code>xml_schema::string</code> type used in the type
+ definitions is a C++ class provided by the XSD runtime
+ that corresponds to built-in XML Schema type
+ <code>string</code>. The <code>xml_schema::string</code>
+ is based on <code>std::string</code> and can be used as
+ such. Similarly, the <code>sequence</code> class template
+ that is used in the <code>name_sequence</code> type
+ definition is based on and has the same interface as
+ <code>std::vector</code>. The mapping between the built-in
+ XML Schema types and C++ types is described in more detail in
+ <a href="#4.5">Section 4.5, "Mapping for the Built-in XML Schema
+ Types"</a>. The <code>hello_t</code> class also includes a
+ constructor with an initializer for the required
+ <code>greeting</code> element as its argument.</p>
+
+ <p>The <code>hello</code> overloaded global functions correspond
+ to the <code>hello</code> global element in XML Schema. A
+ global element in XML Schema is a valid document root.
+ By default XSD generated a set of parsing functions for each
+ global element defined in XML Schema (this can be overridden
+ with the <code>--root-element-*</code> options). Parsing
+ functions return a dynamically allocated object model as an
+ automatic pointer. The actual pointer used depends on the
+ C++ standard selected. For C++11 it is <code>std::unique_ptr</code>
+ as shown above. For C++98 it is <code>std::auto_ptr</code>.
+ For example, if we modify our XSD compiler invocation to
+ select C++98:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --std c++98 hello.xsd
+ </pre>
+
+ <p>Then the parsing function signatures will become:</p>
+
+ <pre class="c++">
+std::auto_ptr&lt;hello_t>
+hello (const std::string&amp; uri);
+
+std::auto_ptr&lt;hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>For more information on parsing functions see <a href="#5">Chapter 5,
+ "Parsing"</a>.</p>
+
+ <h2><a name="2.3">2.3 Implementing Application Logic</a></h2>
+
+ <p>At this point we have all the parts we need to do something useful
+ with the information stored in our XML document:
+ </p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ unique_ptr&lt;hello_t> h (hello (argv[1]));
+
+ for (hello_t::name_const_iterator i (h->name ().begin ());
+ i != h->name ().end ();
+ ++i)
+ {
+ cerr &lt;&lt; h->greeting () &lt;&lt; ", " &lt;&lt; *i &lt;&lt; "!" &lt;&lt; endl;
+ }
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>The first part of our application calls one of the parsing
+ functions to parser an XML file specified in the command line.
+ We then use the returned object model to iterate over names
+ and print a greeting line for each of them. Finally, we
+ catch and print the <code>xml_schema::exception</code>
+ exception in case something goes wrong. This exception
+ is the root of the exception hierarchy used by the
+ XSD-generated code.
+ </p>
+
+
+ <h2><a name="2.4">2.4 Compiling and Running</a></h2>
+
+ <p>After saving our application from the previous section in
+ <code>driver.cxx</code>, we are ready to compile our first
+ program and run it on the test XML document. On a UNIX
+ system this can be done with the following commands:
+ </p>
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx hello.cxx
+$ c++ -std=c++11 -o driver driver.o hello.o -lxerces-c
+$ ./driver hello.xml
+Hello, sun!
+Hello, moon!
+Hello, world!
+ </pre>
+
+ <p>Here <code>.../libxsd</code> represents the path to the
+ <a href="https://cppget.org/libxsd">libxsd</a> package root
+ directory. Note also that we are required to link our
+ application with the Xerces-C++ library because the generated
+ code uses it as the underlying XML parser.</p>
+
+ <h2><a name="2.5">2.5 Adding Serialization</a></h2>
+
+ <p>While parsing and accessing the XML data may be everything
+ you need, there are applications that require creating new
+ or modifying existing XML documents. By default XSD does
+ not produce serialization code. We will need to request
+ it with the <code>--generate-serialization</code> options:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --generate-serialization hello.xsd
+ </pre>
+
+ <p>If we now examine the generated <code>hello.hxx</code> file,
+ we will find a set of overloaded serialization functions,
+ including the following version:</p>
+
+ <pre class="c++">
+void
+hello (std::ostream&amp;,
+ const hello_t&amp;,
+ const xml_schema::namespace_infomap&amp; =
+ xml_schema::namespace_infomap ());
+
+ </pre>
+
+ <p>Just like with parsing functions, XSD generates serialization
+ functions for each global element unless instructed otherwise
+ with one of the <code>--root-element-*</code> options. For more
+ information on serialization functions see <a href="#6">Chapter 6,
+ "Serialization"</a>.</p>
+
+ <p>We first examine an application that modifies an existing
+ object model and serializes it back to XML:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ unique_ptr&lt;hello_t> h (hello (argv[1]));
+
+ // Change the greeting phrase.
+ //
+ h->greeting ("Hi");
+
+ // Add another entry to the name sequence.
+ //
+ h->name ().push_back ("mars");
+
+ // Serialize the modified object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "hello.xsd";
+
+ hello (cout, *h, map);
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>First, our application parses an XML document and obtains its
+ object model as in the previous example. Then it changes the
+ greeting string and adds another entry to the list of names.
+ Finally, it serializes the object model back to XML by calling
+ the serialization function.</p>
+
+ <p>The first argument we pass to the serialization function is
+ <code>cout</code> which results in the XML being written to
+ the standard output for us to inspect. We could have also
+ written the result to a file or memory buffer by creating an
+ instance of <code>std::ofstream</code> or <code>std::ostringstream</code>
+ and passing it instead of <code>cout</code>. The second argument is the
+ object model we want to serialize. The final argument is an optional
+ namespace information map for our vocabulary. It captures information
+ such as namespaces, namespace prefixes to which they should be mapped,
+ and schemas associated with these namespaces. If we don't provide
+ this argument then generic namespace prefixes (<code>p1</code>,
+ <code>p2</code>, etc.) will be automatically assigned to XML namespaces
+ and no schema information will be added to the resulting document
+ (see <a href="#6">Chapter 6, "Serialization"</a> for details).
+ In our case, the prefix (map key) and namespace name are empty
+ because our vocabulary does not use XML namespaces.</p>
+
+ <p>If we now compile and run this application we will see the
+ output as shown in the following listing:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hi&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+ &lt;name>mars&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>We can also create and serialize an object model from scratch
+ as shown in the following example:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include &lt;fstream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ hello_t h ("Hi");
+
+ hello_t::name_sequence&amp; ns (h.name ());
+
+ ns.push_back ("Jane");
+ ns.push_back ("John");
+
+ // Serialize the object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "hello.xsd";
+
+ std::ofstream ofs (argv[1]);
+ hello (ofs, h, map);
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>In this example we used the generated constructor to create
+ an instance of type <code>hello_t</code>. To reduce typing,
+ we obtained a reference to the name sequence which we then
+ used to add a few names. The serialization part is identical
+ to the previous example except this time we are writing to
+ a file. If we compile and run this program, it produces the
+ following XML file:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hi&lt;/greeting>
+
+ &lt;name>Jane&lt;/name>
+ &lt;name>John&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <h2><a name="2.6">2.6 Selecting Naming Convention</a></h2>
+
+ <p>By default XSD uses the so-called K&amp;R (Kernighan and Ritchie)
+ identifier naming convention in the generated code. 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 in the generated code for consistency.
+ XSD 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.</p>
+
+ <p>As an example, let's assume that our "Hello World" application
+ uses the so-called upper-camel-case naming convention for types
+ (that is, each word in a type name is capitalized) and the K&amp;R
+ convention for function names. Since K&amp;R is the default
+ convention for both type and function names, we only need to
+ change the type naming scheme:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --type-naming ucc hello.xsd
+ </pre>
+
+ <p>The <code>ucc</code> argument to the <code>--type-naming</code>
+ options stands for upper-camel-case. If we now examine the
+ generated <code>hello.hxx</code>, we will see the following
+ changes compared to the declarations shown in the previous
+ sections:</p>
+
+ <pre class="c++">
+class Hello_t
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::String GreetingType;
+
+ const GreetingType&amp;
+ greeting () const;
+
+ GreetingType&amp;
+ greeting ();
+
+ void
+ greeting (const GreetingType&amp; x);
+
+ // name
+ //
+ typedef xml_schema::String NameType;
+ typedef xsd::sequence&lt;NameType> NameSequence;
+ typedef NameSequence::iterator NameIterator;
+ typedef NameSequence::const_iterator NameConstIterator;
+
+ const NameSequence&amp;
+ name () const;
+
+ NameSequence&amp;
+ name ();
+
+ void
+ name (const NameSequence&amp; s);
+
+ // Constructor.
+ //
+ Hello_t (const GreetingType&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;Hello_t>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;Hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>Notice that the type names in the <code>xml_schema</code> namespace,
+ for example <code>xml_schema::String</code>, now also use the
+ upper-camel-case naming convention. The only thing that we may
+ be unhappy about in the above code is the <code>_t</code>
+ suffix in <code>Hello_t</code>. If we are not in a position
+ to change the schema, we can <em>touch-up</em> the <code>ucc</code>
+ convention with a custom translation rule using the
+ <code>--type-regex</code> option:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --type-naming ucc --type-regex '/ (.+)_t/\u$1/' hello.xsd
+ </pre>
+
+ <p>This results in the following changes to the generated code:</p>
+
+ <pre class="c++">
+class Hello
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::String GreetingType;
+
+ const GreetingType&amp;
+ greeting () const;
+
+ GreetingType&amp;
+ greeting ();
+
+ void
+ greeting (const GreetingType&amp; x);
+
+ // name
+ //
+ typedef xml_schema::String NameType;
+ typedef xsd::sequence&lt;NameType> NameSequence;
+ typedef NameSequence::iterator NameIterator;
+ typedef NameSequence::const_iterator NameConstIterator;
+
+ const NameSequence&amp;
+ name () const;
+
+ NameSequence&amp;
+ name ();
+
+ void
+ name (const NameSequence&amp; s);
+
+ // Constructor.
+ //
+ Hello (const GreetingType&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;Hello>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;Hello>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>For more detailed information on the <code>--type-naming</code>,
+ <code>--function-naming</code>, <code>--type-regex</code>, and
+ other <code>--*-regex</code> 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>
+
+ <h2><a name="2.7">2.7 Generating Documentation</a></h2>
+
+ <p>While our object model is quite simple, real-world vocabularies
+ can be quite complex with hundreds of types, elements, and
+ attributes. For such vocabularies figuring out which types
+ provide which member functions by studying the generated
+ source code or schemas can be a daunting task. To provide
+ application developers with a more accessible way of
+ understanding the generated object models, the XSD compiler
+ can be instructed to produce source code with documentation
+ comments in the Doxygen format. Then the source code can be
+ processed with the <a href="http://www.doxygen.org">Doxygen</a>
+ documentation system to extract this information and produce
+ documentation in various formats.
+ </p>
+
+ <p>In this section we will see how to generate documentation
+ for our "Hello World" vocabulary. To showcase the full power
+ of the XSD documentation facilities, we will first document
+ our schema. The XSD compiler will then transfer
+ this information from the schema to the generated code and
+ then to the object model documentation. Note that the
+ documentation in the schema is not required for XSD to
+ generate useful documentation. Below you will find
+ our <code>hello.xsd</code> with added documentation:</p>
+
+ <pre class="xml">
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello_t">
+
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The hello_t type consists of a greeting phrase and a
+ collection of names to which this greeting applies.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+
+ &lt;xs:sequence>
+
+ &lt;xs:element name="greeting" type="xs:string">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The greeting element contains the greeting phrase
+ for this hello object.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The name elements contains names to be greeted.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello_t">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The hello element is a root of the Hello XML vocabulary.
+ Every conforming document should start with this element.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>The first step in obtaining the documentation is to recompile
+ our schema with the <code>--generate-doxygen</code> option:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --generate-serialization --generate-doxygen hello.xsd
+ </pre>
+
+ <p>Now the generated <code>hello.hxx</code> file contains comments
+ in the Doxygen format. The next step is to process this file
+ with the Doxygen documentation system. If your project does
+ not use Doxygen then you first need to create a configuration
+ file for your project:</p>
+
+ <pre class="terminal">
+$ doxygen -g hello.doxygen
+ </pre>
+
+ <p>You only need to perform this step once. Now we can generate
+ the documentation by executing the following command in the
+ directory with the generated source code:</p>
+
+ <pre class="terminal">
+$ doxygen hello.doxygen
+ </pre>
+
+ <p>While the generated documentation can be useful as is, we can
+ go one step further and link (using the Doxygen tags mechanism)
+ the documentation for our object model with the documentation
+ for the XSD runtime library which defines C++ classes for the
+ built-in XML Schema types. This way we can seamlessly browse
+ between documentation for the <code>hello_t</code> class which
+ is generated by the XSD compiler and the <code>xml_schema::string</code>
+ class which is defined in the XSD runtime library. The Doxygen
+ configuration file for the XSD runtime is provided with the XSD
+ distribution.</p>
+
+ <p>You can view the result of the steps described in this section
+ on the <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/hello/html/annotated.html">Hello
+ Example Documentation</a> page.</p>
+
+ <!-- Chapater 3 -->
+
+
+ <h1><a name="3">3 Overall Mapping Configuration</a></h1>
+
+ <p>The C++/Tree mapping has a number of configuration parameters that
+ determine the overall properties and behavior of the generated code.
+ Configuration parameters are specified with the XSD command line
+ options. This chapter describes configuration aspects that are most
+ commonly encountered by application developers. These include: the
+ C++ standard, the character type that is used by the generated code,
+ handling of vocabularies that use XML Schema polymorphism, XML Schema
+ to C++ namespace mapping, and thread safety. For more ways to configure
+ the generated code refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>.
+ </p>
+
+ <h2><a name="3.1">3.1 C++ Standard</a></h2>
+
+ <p>The C++/Tree mapping provides support for ISO/IEC C++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</p>
+
+ <h2><a name="3.2">3.2 Character Type and Encoding</a></h2>
+
+ <p>The C++/Tree mapping has built-in support for two character types:
+ <code>char</code> and <code>wchar_t</code>. You can select the
+ character type with the <code>--char-type</code> command line
+ option. The default character type is <code>char</code>. The
+ character type affects all string and string-based types that
+ are used in the mapping. These include the string-based built-in
+ XML Schema types, exception types, stream types, etc.</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. You can select which encoding should be used
+ in the object model 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>
+
+ <p>Note also that the character encoding that is used in the object model
+ is independent of the encodings used in input and output XML. In fact,
+ all three (object mode, input XML, and output XML) can have different
+ encodings.</p>
+
+ <h2><a name="3.3">3.3 Support for Polymorphism</a></h2>
+
+ <p>By default XSD generates non-polymorphic code. If your vocabulary
+ uses XML Schema polymorphism in the form of <code>xsi:type</code>
+ and/or substitution groups, then you will need to compile
+ your schemas with the <code>--generate-polymorphic</code> option
+ to produce polymorphism-aware code. For more information on
+ working with polymorphic object models, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.11">Section 2.11,
+ "Mapping for <code>xsi:type</code> and Substitution Groups"</a> in
+ the C++/Tree Mapping User Manual.</p>
+
+ <h2><a name="3.4">3.4 Namespace Mapping</a></h2>
+
+ <p>XSD maps XML namespaces specified in the <code>targetNamespace</code>
+ attribute in XML Schema to one or more nested C++ namespaces. 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.</p>
+
+ <p>The default mapping of namespace URIs to C++ namespaces
+ can be altered using the <code>--namespace-map</code> and
+ <code>--namespace-regex</code> compiler options. For example,
+ to map namespace URI <code>https://www.codesynthesis.com/my</code> to
+ C++ namespace <code>cs::my</code>, we can use the following option:</p>
+
+ <pre class="terminal">
+--namespace-map https://www.codesynthesis.com/my=cs::my
+ </pre>
+
+ <p>A vocabulary without a namespace is mapped to the global scope. This
+ also can be altered with the above options by using an empty name
+ for the XML namespace:</p>
+
+ <pre class="terminal">
+--namespace-map =cs
+ </pre>
+
+ <h2><a name="3.5">3.5 Thread Safety</a></h2>
+
+ <p>XSD-generated code is thread-safe in the sense that you can
+ use different instantiations of the object model in several
+ threads concurrently. This is possible due to the generated
+ code not relying on any writable global variables. If you need
+ to share the same object between several threads then you will
+ need to provide some form of synchronization. One approach would
+ be to use the generated code customization mechanisms to embed
+ synchronization primitives into the generated C++ classes. For more
+ information on generated code customization refer to the
+ <a href="http://wiki.codesynthesis.com/Tree/Customization_guide">C++/Tree
+ Mapping Customization Guide</a>.</p>
+
+ <p>If you also would like to call parsing and/or serialization
+ functions from several threads potentially concurrently, then
+ you will need to make sure the Xerces-C++ runtime is initialized
+ and terminated only once. The easiest way to do this is to
+ initialize/terminate Xerces-C++ from <code>main()</code> when
+ there are no threads yet/anymore:</p>
+
+ <pre class="c++">
+#include &lt;xercesc/util/PlatformUtils.hpp>
+
+int
+main ()
+{
+ xercesc::XMLPlatformUtils::Initialize ();
+
+ {
+ // Start/terminate threads and parse/serialize here.
+ }
+
+ xercesc::XMLPlatformUtils::Terminate ();
+}
+ </pre>
+
+ <p>Because you initialize the Xerces-C++ runtime yourself you should
+ also pass the <code>xml_schema::flags::dont_initialize</code> flag
+ to parsing and serialization functions. See <a href="#5">Chapter 5,
+ "Parsing"</a> and <a href="#6">Chapter 6, "Serialization"</a> for
+ more information.</p>
+
+
+ <!-- Chapater 4 -->
+
+
+ <h1><a name="4">4 Working with Object Models</a></h1>
+
+ <p>As we have seen in the previous chapters, the XSD compiler generates
+ a C++ class for each type defined in XML Schema. Together these classes
+ constitute an object model for an XML vocabulary. In this chapter we
+ will take a closer look at different elements that comprise an
+ object model class as well as how to create, access, and modify
+ object models.</p>
+
+ <p>In this and subsequent chapters we will use the following schema
+ that describes a collection of person records. We save it in
+ <code>people.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:simpleType name="gender_t">
+ &lt;xs:restriction base="xs:string">
+ &lt;xs:enumeration value="male"/>
+ &lt;xs:enumeration value="female"/>
+ &lt;/xs:restriction>
+ &lt;/xs:simpleType>
+
+ &lt;xs:complexType name="person_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="first-name" type="xs:string"/>
+ &lt;xs:element name="middle-name" type="xs:string" minOccurs="0"/>
+ &lt;xs:element name="last-name" type="xs:string"/>
+ &lt;xs:element name="gender" type="gender_t"/>
+ &lt;xs:element name="age" type="xs:short"/>
+ &lt;/xs:sequence>
+ &lt;xs:attribute name="id" type="xs:unsignedInt" use="required"/>
+ &lt;/xs:complexType>
+
+ &lt;xs:complexType name="people_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="person" type="person_t" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="people" type="people_t"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>A sample XML instance to go along with this schema is saved
+ in <code>people.xml</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+ <p>Compiling <code>people.xsd</code> with the XSD compiler results
+ in three generated C++ classes: <code>gender_t</code>,
+ <code>person_t</code>, and <code>people_t</code>.
+ The <code>gender_t</code> class is modelled after the C++
+ <code>enum</code> type. Its definition is presented below:</p>
+
+ <pre class="c++">
+class gender_t: public xml_schema::string
+{
+public:
+ enum value
+ {
+ male,
+ female
+ };
+
+ gender_t (value);
+ gender_t (const xml_schema::string&amp;);
+
+ gender_t&amp;
+ operator= (value);
+
+ operator value () const;
+};
+ </pre>
+
+ <p>The following listing shows how we can use this type:</p>
+
+ <pre class="c++">
+gender_t m (gender_t::male);
+gender_t f ("female");
+
+if (m == "female" || f == gender_t::male)
+{
+ ...
+}
+
+switch (m)
+{
+case gender_t::male:
+ {
+ ...
+ }
+case gender_t::female:
+ {
+ ...
+ }
+}
+ </pre>
+
+ <p>The other two classes will be examined in detail in the subsequent
+ sections.</p>
+
+ <h2><a name="4.1">4.1 Attribute and Element Cardinalities</a></h2>
+
+ <p>As we have seen in the previous chapters, XSD generates a different
+ set of type definitions and member functions for elements with
+ different cardinalities. The C++/Tree mapping divides all the possible
+ element and attribute cardinalities into three cardinality classes:
+ <em>one</em>, <em>optional</em>, and <em>sequence</em>.</p>
+
+ <p>The <em>one</em> cardinality class covers all elements that should
+ occur exactly once as well as required attributes. In our
+ example, the <code>first-name</code>, <code>last-name</code>,
+ <code>gender</code>, and <code>age</code> elements as well as
+ the <code>id</code> attribute belong to this cardinality class.
+ The following code fragment shows type definitions as well as the
+ accessor and modifier functions that are generated for the
+ <code>gender</code> element in the <code>person_t</code> class:</p>
+
+ <pre class="c++">
+class person_t
+{
+ // gender
+ //
+ typedef gender_t gender_type;
+
+ const gender_type&amp;
+ gender () const;
+
+ gender_type&amp;
+ gender ();
+
+ void
+ gender (const gender_type&amp;);
+};
+ </pre>
+
+ <p>The <code>gender_type</code> type is an alias for the element's type.
+ The first two accessor functions return read-only (constant) and
+ read-write references to the element's value, respectively. The
+ modifier function sets the new value for the element.</p>
+
+ <p>The <em>optional</em> cardinality class covers all elements that
+ can occur zero or one time as well as optional attributes. In our
+ example, the <code>middle-name</code> element belongs to this
+ cardinality class. The following code fragment shows the type
+ definitions as well as the accessor and modifier functions that
+ are generated for this element in the <code>person_t</code> class:</p>
+
+ <pre class="c++">
+class person_t
+{
+ // middle-name
+ //
+ typedef xml_schema::string middle_name_type;
+ typedef xsd::optional&lt;middle_name_type> middle_name_optional;
+
+ const middle_name_optional&amp;
+ middle_name () const;
+
+ middle_name_optional&amp;
+ middle_name ();
+
+ void
+ middle_name (const middle_name_type&amp;);
+
+ void
+ middle_name (const middle_name_optional&amp;);
+};
+ </pre>
+
+ <p>As with the <code>gender</code> element, <code>middle_name_type</code>
+ is an alias for the element's type. The <code>middle_name_optional</code>
+ type is a container for the element's optional value. It can be queried
+ for the presence of the value using the <code>present()</code> function.
+ The value itself can be retrieved using the <code>get()</code>
+ accessor and set using the <code>set()</code> modifier. The container
+ can be reverted to the value not present state with the call to the
+ <code>reset()</code> function. The following example shows how we
+ can use this container:</p>
+
+ <pre class="c++">
+person_t::middle_name_optional n ("John");
+
+if (n.present ())
+{
+ cout &lt;&lt; n.get () &lt;&lt; endl;
+}
+
+n.set ("Jane");
+n.reset ();
+ </pre>
+
+
+ <p>Unlike the <em>one</em> cardinality class, the accessor functions
+ for the <em>optional</em> class return read-only (constant) and
+ read-write references to the container instead of the element's
+ value directly. The modifier functions set the new value for the
+ element.</p>
+
+ <p>Finally, the <em>sequence</em> cardinality class covers all elements
+ that can occur more than once. In our example, the
+ <code>person</code> element in the <code>people_t</code> type
+ belongs to this cardinality class. The following code fragment shows
+ the type definitions as well as the accessor and modifier functions
+ that are generated for this element in the <code>people_t</code>
+ class:</p>
+
+ <pre class="c++">
+class people_t
+{
+ // person
+ //
+ typedef person_t person_type;
+ typedef xsd::sequence&lt;person_type> person_sequence;
+ typedef person_sequence::iterator person_iterator;
+ typedef person_sequence::const_iterator person_const_iterator;
+
+ const person_sequence&amp;
+ person () const;
+
+ person_sequence&amp;
+ person ();
+
+ void
+ person (const person_sequence&amp;);
+};
+ </pre>
+
+ <p>Identical to the other cardinality classes, <code>person_type</code>
+ is an alias for the element's type. The <code>person_sequence</code>
+ type is a sequence container for the element's values. It is based
+ on and has the same interface as <code>std::vector</code> and
+ therefore can be used in similar ways. The <code>person_iterator</code>
+ and <code>person_const_iterator</code> types are read-only
+ (constant) and read-write iterators for the <code>person_sequence</code>
+ container.</p>
+
+ <p>Similar to the <em>optional</em> cardinality class, the
+ accessor functions for the <em>sequence</em> class return
+ read-only (constant) and read-write references to the sequence
+ container. The modifier functions copies the entries from
+ the passed sequence.</p>
+
+ <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 above. 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. To
+ overcome this limitation we can mark certain schema types, for which
+ content order is not sufficiently preserved, as ordered. For more
+ information on this functionality refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.8.4">Section
+ 2.8.4, "Element Order"</a> in the C++/Tree Mapping User Manual.</p>
+
+ <p>For complex schemas with many levels of nested compositors
+ (<code>choice</code> and <code>sequence</code>) it can also
+ be hard to deduce the cardinality class of a particular element.
+ The generated Doxygen documentation can greatly help with
+ this task. For each element and attribute the documentation
+ clearly identifies its cardinality class. Alternatively, you
+ can study the generated header files to find out the cardinality
+ class of a particular attribute or element.</p>
+
+ <p>In the next sections we will examine how to access and modify
+ information stored in an object model using accessor and modifier
+ functions described in this section.</p>
+
+ <h2><a name="4.2">4.2 Accessing the Object Model</a></h2>
+
+ <p>In this section we will learn how to get to the information
+ stored in the object model for our person records vocabulary.
+ The following application accesses and prints the contents
+ of the <code>people.xml</code> file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ unique_ptr&lt;people_t> ppl (people ("people.xml"));
+
+ // Iterate over individual person records.
+ //
+ people_t::person_sequence&amp; ps (ppl->person ());
+
+ for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
+ {
+ person_t&amp; p (*i);
+
+ // Print names: first-name and last-name are required elements,
+ // middle-name is optional.
+ //
+ cout &lt;&lt; "name: " &lt;&lt; p.first_name () &lt;&lt; " ";
+
+ if (p.middle_name ().present ())
+ cout &lt;&lt; p.middle_name ().get () &lt;&lt; " ";
+
+ cout &lt;&lt; p.last_name () &lt;&lt; endl;
+
+ // Print gender, age, and id which are all required.
+ //
+ cout &lt;&lt; "gender: " &lt;&lt; p.gender () &lt;&lt; endl
+ &lt;&lt; "age: " &lt;&lt; p.age () &lt;&lt; endl
+ &lt;&lt; "id: " &lt;&lt; p.id () &lt;&lt; endl
+ &lt;&lt; endl;
+ }
+}
+ </pre>
+
+ <p>This code shows common patterns of accessing elements and attributes
+ with different cardinality classes. For the sequence element
+ (<code>person</code> in <code>people_t</code>) we first obtain a
+ reference to the container and then iterate over individual
+ records. The values of elements and attributes with the
+ <em>one</em> cardinality class (<code>first-name</code>,
+ <code>last-name</code>, <code>gender</code>, <code>age</code>,
+ and <code>id</code>) can be obtained directly by calling the
+ corresponding accessor functions. For the optional element
+ <code>middle-name</code> we first check if the value is present
+ and only then call <code>get()</code> to retrieve it.</p>
+
+ <p>Note that when we want to reduce typing by creating a variable
+ representing a fragment of the object model that we are currently
+ working with (<code>ps</code> and <code>p</code> above), we obtain
+ a reference to that fragment instead of making a potentially
+ expensive copy. This is generally a good rule to follow when
+ creating high-performance applications.</p>
+
+ <p>If we run the above application on our sample
+ <code>people.xml</code>, the output looks as follows:</p>
+
+ <pre class="terminal">
+name: John Doe
+gender: male
+age: 32
+id: 1
+
+name: Jane Mary Doe
+gender: female
+age: 28
+id: 2
+ </pre>
+
+
+ <h2><a name="4.3">4.3 Modifying the Object Model</a></h2>
+
+ <p>In this section we will learn how to modify the information
+ stored in the object model for our person records vocabulary.
+ The following application changes the contents of the
+ <code>people.xml</code> file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ unique_ptr&lt;people_t> ppl (people ("people.xml"));
+
+ // Iterate over individual person records and increment
+ // the age.
+ //
+ people_t::person_sequence&amp; ps (ppl->person ());
+
+ for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
+ {
+ // Alternative way: i->age ()++;
+ //
+ i->age (i->age () + 1);
+ }
+
+ // Add middle-name to the first record and remove it from
+ // the second.
+ //
+ person_t&amp; john (ps[0]);
+ person_t&amp; jane (ps[1]);
+
+ john.middle_name ("Mary");
+ jane.middle_name ().reset ();
+
+ // Add another John record.
+ //
+ ps.push_back (john);
+
+ // Serialize the modified object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "people.xsd";
+
+ people (cout, *ppl, map);
+}
+ </pre>
+
+ <p>The first modification the above application performs is iterating
+ over person records and incrementing the age value. This code
+ fragment shows how to modify the value of a required attribute
+ or element. The next modification shows how to set a new value
+ for the optional <code>middle-name</code> element as well
+ as clear its value. Finally the example adds a copy of the
+ John Doe record to the <code>person</code> element sequence.</p>
+
+ <p>Note that in this case using references for the <code>ps</code>,
+ <code>john</code>, and <code>jane</code> variables is no longer
+ a performance improvement but a requirement for the application
+ to function correctly. If we hadn't used references, all our changes
+ would have been made on copies without affecting the object model.</p>
+
+ <p>If we run the above application on our sample <code>people.xml</code>,
+ the output looks as follows:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>33&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>29&lt;/age>
+ &lt;/person>
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>33&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+
+ <h2><a name="4.4">4.4 Creating the Object Model from Scratch</a></h2>
+
+ <p>In this section we will learn how to create a new object model
+ for our person records vocabulary. The following application
+ recreates the content of the original <code>people.xml</code>
+ file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ people_t ppl;
+ people_t::person_sequence&amp; ps (ppl.person ());
+
+ // Add the John Doe record.
+ //
+ ps.push_back (
+ person_t ("John", // first-name
+ "Doe", // last-name
+ gender_t::male, // gender
+ 32, // age
+ 1));
+
+ // Add the Jane Doe record.
+ //
+ ps.push_back (
+ person_t ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2)); // id
+
+ // Add middle name to the Jane Doe record.
+ //
+ person_t&amp; jane (ps.back ());
+ jane.middle_name ("Mary");
+
+ // Serialize the object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "people.xsd";
+
+ people (cout, ppl, map);
+}
+ </pre>
+
+ <p>The only new part in the above application is the calls
+ to the <code>people_t</code> and <code>person_t</code>
+ constructors. As a general rule, for each C++ class
+ XSD generates a constructor with initializers
+ for each element and attribute belonging to the <em>one</em>
+ cardinality class. For our vocabulary, the following
+ constructors are generated:</p>
+
+ <pre class="c++">
+class person_t
+{
+ person_t (const first_name_type&amp;,
+ const last_name_type&amp;,
+ const gender_type&amp;,
+ const age_type&amp;,
+ const id_type&amp;);
+};
+
+class people_t
+{
+ people_t ();
+};
+ </pre>
+
+ <p>Note also that we set the <code>middle-name</code> element
+ on the Jane Doe record by obtaining a reference to that record
+ in the object model and setting the <code>middle-name</code>
+ value on it. This is a general rule that should be followed
+ in order to obtain the best performance: if possible,
+ direct modifications to the object model should be preferred
+ to modifications on temporaries with subsequent copying. The
+ following code fragment shows a semantically equivalent but
+ slightly slower version:</p>
+
+ <pre class="c++">
+// Add the Jane Doe record.
+//
+person_t jane ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2); // id
+
+jane.middle_name ("Mary");
+
+ps.push_back (jane);
+ </pre>
+
+ <p>We can also go one step further to reduce copying and improve
+ the performance of our application by using the non-copying
+ <code>push_back()</code> function which assumes ownership
+ of the passed objects:</p>
+
+ <pre class="c++">
+// Add the Jane Doe record. C++11 version
+//
+unique_ptr&lt;person_t> jane_p (
+ new person_t ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2)); // id
+ps.push_back (std::move (jane_p)); // assumes ownership
+
+// Add the John Doe record. C++98 version.
+//
+auto_ptr&lt;person_t> john_p (
+ new person_t ("John", // first-name
+ "Doe", // last-name
+ gender_t::male, // gender
+ 32, // age
+ 1));
+ps.push_back (john_p); // assumes ownership
+ </pre>
+
+ <p>For more information on the non-copying modifier functions refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.8">Section
+ 2.8, "Mapping for Local Elements and Attributes"</a> in the C++/Tree Mapping
+ User Manual. The above application produces the following output:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+ <h2><a name="4.5">4.5 Mapping for the Built-in XML Schema Types</a></h2>
+
+ <p>Our person record vocabulary uses several built-in XML Schema
+ types: <code>string</code>, <code>short</code>, and
+ <code>unsignedInt</code>. Until now we haven't talked about
+ the mapping of built-in XML Schema types to C++ types and how
+ to work with them. This section provides an overview
+ of the built-in types. For more detailed information refer
+ to <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.5">Section
+ 2.5, "Mapping for Built-in Data Types"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>In XML Schema, built-in types are defined in the XML Schema namespace.
+ By default, the C++/Tree mapping maps this namespace to C++
+ namespace <code>xml_schema</code> (this mapping can be altered
+ with the <code>--namespace-map</code> option). The following table
+ summarizes the mapping of XML Schema built-in types to C++ types:</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">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><code>xml_schema::qname</code></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>type derived from <code>ncname</code></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><code>xml_schema::base64_binary</code></td>
+ </tr>
+ <tr>
+ <td><code>hexBinary</code></td>
+ <td><code>hex_binary</code></td>
+ <td><code>xml_schema::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><code>xml_schema::date</code></td>
+ </tr>
+ <tr>
+ <td><code>dateTime</code></td>
+ <td><code>date_time</code></td>
+ <td><code>xml_schema::date_time</code></td>
+ </tr>
+ <tr>
+ <td><code>duration</code></td>
+ <td><code>duration</code></td>
+ <td><code>xml_schema::duration</code></td>
+ </tr>
+ <tr>
+ <td><code>gDay</code></td>
+ <td><code>gday</code></td>
+ <td><code>xml_schema::gday</code></td>
+ </tr>
+ <tr>
+ <td><code>gMonth</code></td>
+ <td><code>gmonth</code></td>
+ <td><code>xml_schema::gmonth</code></td>
+ </tr>
+ <tr>
+ <td><code>gMonthDay</code></td>
+ <td><code>gmonth_day</code></td>
+ <td><code>xml_schema::gmonth_day</code></td>
+ </tr>
+ <tr>
+ <td><code>gYear</code></td>
+ <td><code>gyear</code></td>
+ <td><code>xml_schema::gyear</code></td>
+ </tr>
+ <tr>
+ <td><code>gYearMonth</code></td>
+ <td><code>gyear_month</code></td>
+ <td><code>xml_schema::gyear_month</code></td>
+ </tr>
+ <tr>
+ <td><code>time</code></td>
+ <td><code>time</code></td>
+ <td><code>xml_schema::time</code></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>As you can see from the table above a number of built-in
+ XML Schema types are mapped to fundamental C++ types such
+ as <code>int</code> or <code>bool</code>. All string-based
+ XML Schema types are mapped to C++ types that are derived
+ from either <code>std::string</code> or
+ <code>std::wstring</code>, depending on the character
+ type selected. For access and modification purposes these
+ types can be treated as <code>std::string</code>. A number
+ of built-in types, such as <code>qname</code>, the binary
+ types, and the date/time types do not have suitable
+ fundamental or standard C++ types to map to. As a result,
+ these types are implemented from scratch in the XSD runtime.
+ For more information on their interfaces refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.5">Section
+ 2.5, "Mapping for Built-in Data Types"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+
+ <!-- Chapater 5 -->
+
+
+ <h1><a name="5">5 Parsing</a></h1>
+
+ <p>We have already seen how to parse XML to an object model in this guide
+ before. In this chapter we will discuss the parsing topic in more
+ detail.</p>
+
+ <p>By default, the C++/Tree mapping provides a total of 14 overloaded
+ parsing functions. They differ in the input methods used to
+ read XML as well as the error reporting mechanisms. It is also possible
+ to generate types for root elements instead of parsing and serialization
+ functions. This may be useful if your XML vocabulary has multiple
+ root elements. For more information on element types refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.9">Section
+ 2.9, "Mapping for Global Elements"</a> in the C++/Tree Mapping User
+ Manual.</p>
+
+
+ <p>In this section we will discuss the most commonly used versions of
+ the parsing functions. For a comprehensive description of parsing
+ refer to <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#3">Chapter
+ 3, "Parsing"</a> in the C++/Tree Mapping User Manual. For the <code>people</code>
+ global element from our person record vocabulary, we will concentrate
+ on the following three parsing functions:</p>
+
+ <pre class="c++">
+std::[unique|auto]_ptr&lt;people_t>
+people (const std::string&amp; uri,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;people_t>
+people (std::istream&amp; is,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;people_t>
+people (std::istream&amp; is,
+ const std::string&amp; resource_id,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = ::xml_schema::properties ());
+ </pre>
+
+ <p>The first function parses a local file or a URI. We have already
+ used this parsing function in the previous chapters. The second
+ and third functions read XML from a standard input stream. The
+ last function also requires a resource id. This id is used to
+ identify the XML document being parser in diagnostics messages
+ as well as to resolve relative paths to other documents (for example,
+ schemas) that might be referenced from the XML document.</p>
+
+ <p>The last two arguments to all three parsing functions are parsing
+ flags and properties. The flags argument provides a number of ways
+ to fine-tune the parsing process. The properties argument allows
+ to pass additional information to the parsing functions. We will
+ use these two arguments in <a href="#5.1">Section 5.1, "XML Schema
+ Validation and Searching"</a> below. All three functions return
+ the object model as either <code>std::unique_ptr</code> (C++11) or
+ <code>std::auto_ptr</code> (C++98), depending on the C++ standard
+ selected (<code>--std</code> XSD compiler option). The following
+ example shows how we can use the above parsing functions:</p>
+
+ <pre class="c++">
+using std::unique_ptr;
+
+// Parse a local file or URI.
+//
+unique_ptr&lt;people_t> p1 (people ("people.xml"));
+unique_ptr&lt;people_t> p2 (people ("http://example.com/people.xml"));
+
+// Parse a local file via ifstream.
+//
+std::ifstream ifs ("people.xml");
+unique_ptr&lt;people_t> p3 (people (ifs, "people.xml"));
+
+// Parse an XML string.
+//
+std::string str ("..."); // XML in a string.
+std::istringstream iss (str);
+unique_ptr&lt;people_t> p4 (people (iss));
+ </pre>
+
+
+ <h2><a name="5.1">5.1 XML Schema Validation and Searching</a></h2>
+
+ <p>The C++/Tree mapping relies on the underlying Xerces-C++ XML
+ parser for full XML document validation. The XML Schema
+ validation is enabled by default and can be disabled by
+ passing the <code>xml_schema::flags::dont_validate</code>
+ flag to the parsing functions, for example:</p>
+
+ <pre class="c++">
+unique_ptr&lt;people_t> p (
+ people ("people.xml", xml_schema::flags::dont_validate));
+ </pre>
+
+ <p>Even when XML Schema validation is disabled, the generated
+ code still performs a number of checks to prevent
+ construction of an inconsistent object model (for example, an
+ object model with missing required attributes or elements).</p>
+
+ <p>When XML Schema validation is enabled, the XML parser needs
+ to locate a schema to validate against. There are several
+ methods to provide the schema location information to the
+ parser. The easiest and most commonly used method is to
+ specify schema locations in the XML document itself
+ with the <code>schemaLocation</code> or
+ <code>noNamespaceSchemaLocation</code> attributes, for example:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd"
+ xsi:schemaLocation="http://www.w3.org/XML/1998/namespace xml.xsd">
+ </pre>
+
+ <p>As you might have noticed, we used this method in all the sample XML
+ documents presented in this guide up until now. Note that the
+ schema locations specified with these two attributes are relative
+ to the document's path unless they are absolute URIs (that is
+ start with <code>http://</code>, <code>file://</code>, etc.).
+ In particular, if you specify just file names as your schema
+ locations, as we did above, then the schemas should reside in
+ the same directory as the XML document itself.</p>
+
+ <p>Another method of providing the schema location information
+ is via the <code>xml_schema::properties</code> argument, as
+ shown in the following example:</p>
+
+ <pre class="c++">
+xml_schema::properties props;
+props.no_namespace_schema_location ("people.xsd");
+props.schema_location ("http://www.w3.org/XML/1998/namespace", "xml.xsd");
+
+unique_ptr&lt;people_t> p (people ("people.xml", 0, props));
+ </pre>
+
+ <p>The schema locations provided with this method overrides
+ those specified in the XML document. As with the previous
+ method, the schema locations specified this way are
+ relative to the document's path unless they are absolute URIs.
+ In particular, if you want to use local schemas that are
+ not related to the document being parsed, then you will
+ need to use the <code>file://</code> URI. The following
+ example shows how to use schemas that reside in the current
+ working directory:</p>
+
+ <pre class="c++">
+#include &lt;unistd.h> // getcwd
+#include &lt;limits.h> // PATH_MAX
+
+char cwd[PATH_MAX];
+if (getcwd (cwd, PATH_MAX) == 0)
+{
+ // Buffer too small?
+}
+
+xml_schema::properties props;
+
+props.no_namespace_schema_location (
+ "file:///" + std::string (cwd) + "/people.xsd");
+
+props.schema_location (
+ "http://www.w3.org/XML/1998/namespace",
+ "file:///" + std::string (cwd) + "/xml.xsd");
+
+unique_ptr&lt;people_t> p (people ("people.xml", 0, props));
+ </pre>
+
+ <p>A third method is the most useful if you are planning to parse
+ several XML documents of the same vocabulary. In that case
+ it may be beneficial to pre-parse and cache the schemas in
+ the XML parser which can then be used to parse all documents
+ without re-parsing the schemas. For more information on
+ this method refer to the <code>caching</code> example in the
+ <code>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.
+ It is also possible to convert the schemas into a pre-compiled
+ binary representation and embed this representation directly into
+ the application executable. With this approach your application can
+ perform XML Schema validation without depending on any external
+ schema files. For more information on how to achieve this refer to
+ the <code>embedded</code> example in the <code>cxx/tree/</code>
+ directory in the <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</p>
+
+ <p>When the XML parser cannot locate a schema for the
+ XML document, the validation fails and XML document
+ elements and attributes for which schema definitions could
+ not be located are reported in the diagnostics. For
+ example, if we remove the <code>noNamespaceSchemaLocation</code>
+ attribute in <code>people.xml</code> from the previous chapter,
+ then we will get the following diagnostics if we try to parse
+ this file with validation enabled:</p>
+
+ <pre class="terminal">
+people.xml:2:63 error: no declaration found for element 'people'
+people.xml:4:18 error: no declaration found for element 'person'
+people.xml:4:18 error: attribute 'id' is not declared for element 'person'
+people.xml:5:17 error: no declaration found for element 'first-name'
+people.xml:6:18 error: no declaration found for element 'middle-name'
+people.xml:7:16 error: no declaration found for element 'last-name'
+people.xml:8:13 error: no declaration found for element 'gender'
+people.xml:9:10 error: no declaration found for element 'age'
+ </pre>
+
+ <h2><a name="5.2">5.2 Error Handling</a></h2>
+
+ <p>The parsing functions offer a number of ways to handle error conditions
+ with the C++ exceptions being the most commonly used mechanism. All
+ C++/Tree exceptions derive from common base <code>xml_schema::exception</code>
+ which in turn derives from <code>std::exception</code>. The easiest
+ way to uniformly handle all possible C++/Tree exceptions and print
+ detailed information about the error is to catch and print
+ <code>xml_schema::exception</code>, as shown in the following
+ example:</p>
+
+ <pre class="c++">
+try
+{
+ unique_ptr&lt;people_t> p (people ("people.xml"));
+}
+catch (const xml_schema::exception&amp; e)
+{
+ cerr &lt;&lt; e &lt;&lt; endl;
+}
+ </pre>
+
+ <p>Each individual C++/Tree exception also allows you to obtain
+ error details programmatically. For example, the
+ <code>xml_schema::parsing</code> exception is thrown when
+ the XML parsing and validation in the underlying XML parser
+ fails. It encapsulates various diagnostics information
+ such as the file name, line and column numbers, as well as the
+ error or warning message for each entry. For more information
+ about this and other exceptions that can be thrown during
+ parsing, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#3.3">Section
+ 3.3, "Error Handling"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>Note that if you are parsing <code>std::istream</code> on which
+ exceptions are not enabled, then you will need to check the
+ stream state after the call to the parsing function in order
+ to detect any possible stream failures, for example:</p>
+
+ <pre class="c++">
+std::ifstream ifs ("people.xml");
+
+if (ifs.fail ())
+{
+ cerr &lt;&lt; "people.xml: unable to open" &lt;&lt; endl;
+ return 1;
+}
+
+unique_ptr&lt;people_t> p (people (ifs, "people.xml"));
+
+if (ifs.fail ())
+{
+ cerr &lt;&lt; "people.xml: read error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions as
+ shown below:</p>
+
+ <pre class="c++">
+try
+{
+ std::ifstream ifs;
+ ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
+ ifs.open ("people.xml");
+
+ unique_ptr&lt;people_t> p (people (ifs, "people.xml"));
+}
+catch (const std::ifstream::failure&amp;)
+{
+ cerr &lt;&lt; "people.xml: unable to open or read error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+
+ <!-- Chapater 6 -->
+
+
+ <h1><a name="6">6 Serialization</a></h1>
+
+ <p>We have already seen how to serialize an object model back to XML
+ in this guide before. In this chapter we will discuss the
+ serialization topic in more detail.</p>
+
+ <p>By default, the C++/Tree mapping provides a total of 8 overloaded
+ serialization functions. They differ in the output methods used to write
+ XML as well as the error reporting mechanisms. It is also possible to
+ generate types for root elements instead of parsing and serialization
+ functions. This may be useful if your XML vocabulary has multiple
+ root elements. For more information on element types refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.9">Section
+ 2.9, "Mapping for Global Elements"</a> in the C++/Tree Mapping User
+ Manual.</p>
+
+
+ <p>In this section we will discuss the most commonly
+ used version of serialization functions. For a comprehensive description
+ of serialization refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#4">Chapter
+ 4, "Serialization"</a> in the C++/Tree Mapping User Manual. For the
+ <code>people</code> global element from our person record vocabulary,
+ we will concentrate on the following serialization function:</p>
+
+ <pre class="c++">
+void
+people (std::ostream&amp; os,
+ const people_t&amp; x,
+ const xml_schema::namespace_infomap&amp; map =
+ xml_schema::namespace_infomap (),
+ const std::string&amp; encoding = "UTF-8",
+ xml_schema::flags f = 0);
+ </pre>
+
+ <p>This function serializes the object model passed as the second
+ argument to the standard output stream passed as the first
+ argument. The third argument is a namespace information map
+ which we will discuss in more detail in the next section.
+ The fourth argument is a character encoding that the resulting
+ XML document should be in. Possible valid values for this
+ argument are "US-ASCII", "ISO8859-1", "UTF-8", "UTF-16BE",
+ "UTF-16LE", "UCS-4BE", and "UCS-4LE". Finally, the flags
+ argument allows fine-tuning of the serialization process.
+ The following example shows how we can use the above serialization
+ function:</p>
+
+ <pre class="c++">
+people_t&amp; p = ...
+
+xml_schema::namespace_infomap map;
+map[""].schema = "people.xsd";
+
+// Serialize to stdout.
+//
+people (std::cout, p, map);
+
+// Serialize to a file.
+//
+std::ofstream ofs ("people.xml");
+people (ofs, p, map);
+
+// Serialize to a string.
+//
+std::ostringstream oss;
+people (oss, p, map);
+std::string xml (oss.str ());
+ </pre>
+
+
+ <h2><a name="6.1">6.1 Namespace and Schema Information</a></h2>
+
+ <p>While XML serialization can be done just from the object
+ model alone, it is often desirable to assign meaningful
+ prefixes to XML namespaces used in the vocabulary as
+ well as to provide the schema location information.
+ This is accomplished by passing the namespace information
+ map to the serialization function. The key in this map is
+ a namespace prefix that should be assigned to an XML namespace
+ specified in the <code>name</code> variable of the
+ map value. You can also assign an optional schema location for
+ this namespace in the <code>schema</code> variable. Based
+ on each key-value entry in this map, the serialization
+ function adds two attributes to the resulting XML document:
+ the namespace-prefix mapping attribute and schema location
+ attribute. The empty prefix indicates that the namespace
+ should be mapped without a prefix. For example, the following
+ map:</p>
+
+ <pre class="c++">
+xml_schema::namespace_infomap map;
+
+map[""].name = "http://www.example.com/example";
+map[""].schema = "example.xsd";
+
+map["x"].name = "http://www.w3.org/XML/1998/namespace";
+map["x"].schema = "xml.xsd";
+ </pre>
+
+ <p>Results in the following XML document:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;example
+ xmlns="http://www.example.com/example"
+ xmlns:x="http://www.w3.org/XML/1998/namespace"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.example.com/example example.xsd
+ http://www.w3.org/XML/1998/namespace xml.xsd">
+ </pre>
+
+ <p>The empty namespace indicates that the vocabulary has no target
+ namespace. For example, the following map results in only the
+ <code>noNamespaceSchemaLocation</code> attribute being added:</p>
+
+ <pre class="c++">
+xml_schema::namespace_infomap map;
+
+map[""].name = "";
+map[""].schema = "example.xsd";
+ </pre>
+
+ <h2><a name="6.2">6.2 Error Handling</a></h2>
+
+ <p>Similar to the parsing functions, the serialization functions offer a
+ number of ways to handle error conditions with the C++ exceptions being
+ the most commonly used mechanisms. As with parsing, the easiest way to
+ uniformly handle all possible serialization exceptions and print
+ detailed information about the error is to catch and print
+ <code>xml_schema::exception</code>:</p>
+
+ <pre class="c++">
+try
+{
+ people_t&amp; p = ...
+
+ xml_schema::namespace_infomap map;
+ map[""].schema = "people.xsd";
+
+ people (std::cout, p, map));
+}
+catch (const xml_schema::exception&amp; e)
+{
+ cerr &lt;&lt; e &lt;&lt; endl;
+}
+ </pre>
+
+ <p>The most commonly encountered serialization exception is
+ <code>xml_schema::serialization</code>. It is thrown
+ when the XML serialization in the underlying XML writer
+ fails. It encapsulates various diagnostics information
+ such as the file name, line and column numbers, as well as the
+ error or warning message for each entry. For more information
+ about this and other exceptions that can be thrown during
+ serialization, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#4.4">Section
+ 4.4, "Error Handling"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>Note that if you are serializing to <code>std::ostream</code> on
+ which exceptions are not enabled, then you will need to check the
+ stream state after the call to the serialization function in order
+ to detect any possible stream failures, for example:</p>
+
+ <pre class="c++">
+std::ofstream ofs ("people.xml");
+
+if (ofs.fail ())
+{
+ cerr &lt;&lt; "people.xml: unable to open" &lt;&lt; endl;
+ return 1;
+}
+
+people (ofs, p, map));
+
+if (ofs.fail ())
+{
+ cerr &lt;&lt; "people.xml: write error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions as
+ shown below:</p>
+
+ <pre class="c++">
+try
+{
+ std::ofstream ofs;
+ ofs.exceptions (std::ofstream::badbit | std::ofstream::failbit);
+ ofs.open ("people.xml");
+
+ people (ofs, p, map));
+}
+catch (const std::ofstream::failure&amp;)
+{
+ cerr &lt;&lt; "people.xml: unable to open or write error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ </div>
+</div>
+
+</body>
+</html>
diff --git a/doc/cxx/tree/guide/index.xhtml.in b/doc/cxx/tree/guide/index.xhtml.in
new file mode 100644
index 0000000..2f7f1e2
--- /dev/null
+++ b/doc/cxx/tree/guide/index.xhtml.in
@@ -0,0 +1,2736 @@
+<?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 Getting Started Guide</title>
+
+ <meta name="copyright" content="&#169; @copyright@"/>
+ <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,parsing,serialization,validation"/>
+ <meta name="description" content="C++/Tree Mapping Getting Started Guide"/>
+
+ <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%;
+ line-height: 1.2em;
+ }
+
+ h2 {
+ font-weight : bold;
+ font-size : 150%;
+
+ padding-top : 0.8em;
+ }
+
+ h3 {
+ font-size : 140%;
+ 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;
+ }
+
+ #titlepage #first-title {
+ padding: 1em 0 0.4em 0;
+ }
+
+ #titlepage #second-title {
+ padding: 0.4em 0 2em 0;
+ }
+
+ /* Lists */
+ ul.list li {
+ padding-top : 0.3em;
+ padding-bottom : 0.3em;
+ }
+
+ div.img {
+ text-align: center;
+ padding: 2em 0 2em 0;
+ }
+
+ /* */
+ dl dt {
+ padding : 0.8em 0 0 0;
+ }
+
+ /* 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;
+ }
+
+ /* 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 class="title" id="first-title">C++/Tree Mapping</div>
+ <div class="title" id="second-title">Getting Started Guide</div>
+
+ <p>Copyright &#169; @copyright@.</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/guide/index.xhtml">XHTML</a>,
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-tree-guide.pdf">PDF</a>, and
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/guide/cxx-tree-guide.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>
+ <table class="toc">
+ <tr><th>1.1</th><td><a href="#1.1">Mapping Overview</a></td></tr>
+ <tr><th>1.2</th><td><a href="#1.2">Benefits</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>2</th><td><a href="#2">Hello World Example</a>
+ <table class="toc">
+ <tr><th>2.1</th><td><a href="#2.1">Writing XML Document and Schema</a></td></tr>
+ <tr><th>2.2</th><td><a href="#2.2">Translating Schema to C++</a></td></tr>
+ <tr><th>2.3</th><td><a href="#2.3">Implementing Application Logic</a></td></tr>
+ <tr><th>2.4</th><td><a href="#2.4">Compiling and Running</a></td></tr>
+ <tr><th>2.5</th><td><a href="#2.5">Adding Serialization</a></td></tr>
+ <tr><th>2.6</th><td><a href="#2.6">Selecting Naming Convention</a></td></tr>
+ <tr><th>2.7</th><td><a href="#2.7">Generating Documentation</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>3</th><td><a href="#3">Overall Mapping Configuration</a>
+ <table class="toc">
+ <tr><th>3.1</th><td><a href="#3.1">C++ Standard</a></td></tr>
+ <tr><th>3.2</th><td><a href="#3.2">Character Type and Encoding</a></td></tr>
+ <tr><th>3.3</th><td><a href="#3.3">Support for Polymorphism </a></td></tr>
+ <tr><th>3.4</th><td><a href="#3.4">Namespace Mapping</a></td></tr>
+ <tr><th>3.5</th><td><a href="#3.5">Thread Safety</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>4</th><td><a href="#4">Working with Object Models</a>
+ <table class="toc">
+ <tr><th>4.1</th><td><a href="#4.1">Attribute and Element Cardinalities</a></td></tr>
+ <tr><th>4.2</th><td><a href="#4.2">Accessing the Object Model</a></td></tr>
+ <tr><th>4.3</th><td><a href="#4.3">Modifying the Object Model</a></td></tr>
+ <tr><th>4.4</th><td><a href="#4.4">Creating the Object Model from Scratch</a></td></tr>
+ <tr><th>4.5</th><td><a href="#4.5">Mapping for the Built-in XML Schema Types</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>5</th><td><a href="#5">Parsing</a>
+ <table class="toc">
+ <tr><th>5.1</th><td><a href="#5.1">XML Schema Validation and Searching</a></td></tr>
+ <tr><th>5.2</th><td><a href="#5.2">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ <tr>
+ <th>6</th><td><a href="#6">Serialization</a>
+ <table class="toc">
+ <tr><th>6.1</th><td><a href="#6.1">Namespace and Schema Information</a></td></tr>
+ <tr><th>6.2</th><td><a href="#6.2">Error Handling</a></td></tr>
+ </table>
+ </td>
+ </tr>
+
+ </table>
+ </div>
+
+ <h1><a name="0">Preface</a></h1>
+
+ <h2><a name="0.1">About This Document</a></h2>
+
+ <p>The goal of this document is to provide you with an understanding of
+ the C++/Tree programming model and allow you to efficiently evaluate
+ XSD against your project's technical requirements. As such, this
+ document is intended for C++ developers and software architects
+ who are looking for an XML processing solution. For a more in-depth
+ description of the C++/Tree mapping refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/">C++/Tree
+ Mapping User Manual</a>.</p>
+
+ <p>Prior experience with XML and C++ is required to understand this
+ document. Basic understanding of XML Schema is advantageous but
+ not expected or required.
+ </p>
+
+
+ <h2><a name="0.2">More Information</a></h2>
+
+ <p>Beyond this guide, 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/manual/">C++/Tree
+ Mapping User Manual</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</li>
+
+ <li>The <a href="https://www.codesynthesis.com/mailman/listinfo/xsd-users">xsd-users</a>
+ mailing list is the place to ask technical questions about XSD and the C++/Parser mapping.
+ Furthermore, the <a href="https://www.codesynthesis.com/pipermail/xsd-users/">archives</a>
+ may already have answers to some of your questions.</li>
+ </ul>
+
+ <!-- Introduction -->
+
+ <h1><a name="1">1 Introduction</a></h1>
+
+ <p>Welcome to CodeSynthesis XSD and the C++/Tree mapping. XSD is a
+ cross-platform W3C XML Schema to C++ data binding compiler. 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.
+ </p>
+
+ <h2><a name="1.1">1.1 Mapping Overview</a></h2>
+
+ <p>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. The core of the mapping consists of C++
+ classes that constitute the object model and are derived from
+ types defined in XML Schema as well as XML parsing and
+ serialization code.</p>
+
+ <p>Besides the core features, C++/Tree provide a number of additional
+ mapping elements that can be useful in some applications. These
+ include serialization and extraction to/from formats others than
+ XML, such as unstructured text (useful for debugging) and binary
+ representations such as XDR and CDR for high-speed data processing
+ as well as automatic documentation generation. The C++/Tree mapping
+ also provides a wide range of mechanisms for controlling and
+ customizing the generated code.</p>
+
+ <p>A typical application that uses C++/Tree for XML processing usually
+ performs the following three steps: it first reads (parses) an XML
+ document to an in-memory object model, it then performs some useful
+ computations on that object model which may involve modification
+ of the model, and finally it may write (serialize) the modified
+ object model back to XML.</p>
+
+ <p>The next chapter presents a simple application that performs these
+ three steps. The following chapters show how to use the C++/Tree
+ mapping in more detail.</p>
+
+ <h2><a name="1.2">1.2 Benefits</a></h2>
+
+ <p>Traditional XML access APIs such as Document Object Model (DOM)
+ or Simple API for XML (SAX) have a number of drawbacks that
+ make them less suitable for creating robust and maintainable
+ XML processing applications. These drawbacks include:
+ </p>
+
+ <ul class="list">
+ <li>Generic representation of XML in terms of elements, attributes,
+ and text forces an application developer to write a substantial
+ amount of bridging code that identifies and transforms pieces
+ of information encoded in XML to a representation more suitable
+ for consumption by the application logic.</li>
+
+ <li>String-based flow control defers error detection to runtime.
+ It also reduces code readability and maintainability.</li>
+
+ <li>Lack of type safety because the data is represented as text.</li>
+
+ <li>Resulting applications are hard to debug, change, and
+ maintain.</li>
+ </ul>
+
+ <p>In contrast, statically-typed, vocabulary-specific object model
+ produced by the C++/Tree mapping allows you to operate in your
+ domain terms instead of the generic elements, attributes, and
+ text. Static typing helps catch errors at compile-time rather
+ than at run-time. Automatic code generation frees you for more
+ interesting tasks (such as doing something useful with the
+ information stored in the XML documents) and minimizes the
+ effort needed to adapt your applications to changes in the
+ document structure. To summarize, the C++/Tree object model has
+ the following key advantages over generic XML access APIs:</p>
+
+ <ul class="list">
+ <li><b>Ease of use.</b> The generated code hides all the complexity
+ associated with parsing and serializing XML. This includes navigating
+ the structure and converting between the text representation and
+ data types suitable for manipulation by the application
+ logic.</li>
+
+ <li><b>Natural representation.</b> The object representation allows
+ you to access the XML data using your domain vocabulary instead
+ of generic elements, attributes, and text.</li>
+
+ <li><b>Concise code.</b> With the object representation the
+ application implementation is simpler and thus easier
+ to read and understand.</li>
+
+ <li><b>Safety.</b> The generated object model is statically
+ typed and uses functions instead of strings to access the
+ information. This helps catch programming errors at compile-time
+ rather than at runtime.</li>
+
+ <li><b>Maintainability.</b> Automatic code generation minimizes the
+ effort needed to adapt the application to changes in the
+ document structure. With static typing, the C++ compiler
+ can pin-point the places in the client code that need to be
+ changed.</li>
+
+ <li><b>Compatibility.</b> Sequences of elements are represented in
+ the object model as containers conforming to the standard C++
+ sequence requirements. This makes it possible to use standard
+ C++ algorithms on the object representation and frees you from
+ learning yet another container interface, as is the case with
+ DOM.</li>
+
+ <li><b>Efficiency.</b> If the application makes repetitive use
+ of the data extracted from XML, then the C++/Tree object model
+ is more efficient because the navigation is performed using
+ function calls rather than string comparisons and the XML
+ data is extracted only once. Furthermore, the runtime memory
+ usage is reduced due to more efficient data storage
+ (for instance, storing numeric data as integers instead of
+ strings) as well as the static knowledge of cardinality
+ constraints.</li>
+ </ul>
+
+
+ <!-- Hello World Parser -->
+
+
+ <h1><a name="2">2 Hello World Example</a></h1>
+
+ <p>In this chapter we will examine how to parse, access, modify, and
+ serialize a very simple XML document using the XSD-generated
+ C++/Tree object model. The code presented in this chapter is
+ based on the <code>hello</code> example which can be found in
+ the <code>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.</p>
+
+ <h2><a name="2.1">2.1 Writing XML Document and Schema</a></h2>
+
+ <p>First, we need to get an idea about the structure
+ of the XML documents we are going to process. Our
+ <code>hello.xml</code>, for example, could look like this:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello>
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>Then we can write a description of the above XML in the
+ XML Schema language and save it into <code>hello.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="greeting" type="xs:string"/>
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello_t"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>Even if you are not familiar with XML Schema, it
+ should be easy to connect declarations in <code>hello.xsd</code>
+ to elements in <code>hello.xml</code>. The <code>hello_t</code> type
+ is defined as a sequence of the nested <code>greeting</code> and
+ <code>name</code> elements. Note that the term sequence in XML
+ Schema means that elements should appear in a particular order
+ as opposed to appearing multiple times. The <code>name</code>
+ element has its <code>maxOccurs</code> property set to
+ <code>unbounded</code> which means it can appear multiple times
+ in an XML document. Finally, the globally-defined <code>hello</code>
+ element prescribes the root element for our vocabulary. For an
+ easily-approachable introduction to XML Schema refer to
+ <a href="http://www.w3.org/TR/xmlschema-0/">XML Schema Part 0:
+ Primer</a>.</p>
+
+ <p>The above schema is a specification of our XML vocabulary; it tells
+ everybody what valid documents of our XML-based language should look
+ like. We can also update our <code>hello.xml</code> to include the
+ information about the schema so that XML parsers can validate
+ our document:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hello&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+
+ <p>The next step is to compile the schema to generate the object
+ model and parsing functions.</p>
+
+ <h2><a name="2.2">2.2 Translating Schema to C++</a></h2>
+
+ <p>Now we are ready to translate our <code>hello.xsd</code> to C++.
+ To do this we invoke the XSD compiler from a terminal (UNIX) or
+ a command prompt (Windows):
+ </p>
+
+ <pre class="terminal">
+$ xsd cxx-tree hello.xsd
+ </pre>
+
+ <p>The XSD compiler produces two C++ files: <code>hello.hxx</code> and
+ <code>hello.cxx</code>. The following code fragment is taken from
+ <code>hello.hxx</code>; it should give you an idea about what gets
+ generated:
+ </p>
+
+ <pre class="c++">
+class hello_t
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::string greeting_type;
+
+ const greeting_type&amp;
+ greeting () const;
+
+ greeting_type&amp;
+ greeting ();
+
+ void
+ greeting (const greeting_type&amp; x);
+
+ // name
+ //
+ typedef xml_schema::string name_type;
+ typedef xsd::sequence&lt;name_type> name_sequence;
+ typedef name_sequence::iterator name_iterator;
+ typedef name_sequence::const_iterator name_const_iterator;
+
+ const name_sequence&amp;
+ name () const;
+
+ name_sequence&amp;
+ name ();
+
+ void
+ name (const name_sequence&amp; s);
+
+ // Constructor.
+ //
+ hello_t (const greeting_type&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;hello_t>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>The <code>hello_t</code> C++ class corresponds to the
+ <code>hello_t</code> XML Schema type. For each element
+ in this type a set of C++ type definitions as well as
+ accessor and modifier functions are generated inside the
+ <code>hello_t</code> class. Note that the type definitions
+ and member functions for the <code>greeting</code> and
+ <code>name</code> elements are different because of the
+ cardinality differences between these two elements
+ (<code>greeting</code> is a required single element and
+ <code>name</code> is a sequence of elements).</p>
+
+ <p>The <code>xml_schema::string</code> type used in the type
+ definitions is a C++ class provided by the XSD runtime
+ that corresponds to built-in XML Schema type
+ <code>string</code>. The <code>xml_schema::string</code>
+ is based on <code>std::string</code> and can be used as
+ such. Similarly, the <code>sequence</code> class template
+ that is used in the <code>name_sequence</code> type
+ definition is based on and has the same interface as
+ <code>std::vector</code>. The mapping between the built-in
+ XML Schema types and C++ types is described in more detail in
+ <a href="#4.5">Section 4.5, "Mapping for the Built-in XML Schema
+ Types"</a>. The <code>hello_t</code> class also includes a
+ constructor with an initializer for the required
+ <code>greeting</code> element as its argument.</p>
+
+ <p>The <code>hello</code> overloaded global functions correspond
+ to the <code>hello</code> global element in XML Schema. A
+ global element in XML Schema is a valid document root.
+ By default XSD generated a set of parsing functions for each
+ global element defined in XML Schema (this can be overridden
+ with the <code>--root-element-*</code> options). Parsing
+ functions return a dynamically allocated object model as an
+ automatic pointer. The actual pointer used depends on the
+ C++ standard selected. For C++11 it is <code>std::unique_ptr</code>
+ as shown above. For C++98 it is <code>std::auto_ptr</code>.
+ For example, if we modify our XSD compiler invocation to
+ select C++98:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --std c++98 hello.xsd
+ </pre>
+
+ <p>Then the parsing function signatures will become:</p>
+
+ <pre class="c++">
+std::auto_ptr&lt;hello_t>
+hello (const std::string&amp; uri);
+
+std::auto_ptr&lt;hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>For more information on parsing functions see <a href="#5">Chapter 5,
+ "Parsing"</a>.</p>
+
+ <h2><a name="2.3">2.3 Implementing Application Logic</a></h2>
+
+ <p>At this point we have all the parts we need to do something useful
+ with the information stored in our XML document:
+ </p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ unique_ptr&lt;hello_t> h (hello (argv[1]));
+
+ for (hello_t::name_const_iterator i (h->name ().begin ());
+ i != h->name ().end ();
+ ++i)
+ {
+ cerr &lt;&lt; h->greeting () &lt;&lt; ", " &lt;&lt; *i &lt;&lt; "!" &lt;&lt; endl;
+ }
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>The first part of our application calls one of the parsing
+ functions to parser an XML file specified in the command line.
+ We then use the returned object model to iterate over names
+ and print a greeting line for each of them. Finally, we
+ catch and print the <code>xml_schema::exception</code>
+ exception in case something goes wrong. This exception
+ is the root of the exception hierarchy used by the
+ XSD-generated code.
+ </p>
+
+
+ <h2><a name="2.4">2.4 Compiling and Running</a></h2>
+
+ <p>After saving our application from the previous section in
+ <code>driver.cxx</code>, we are ready to compile our first
+ program and run it on the test XML document. On a UNIX
+ system this can be done with the following commands:
+ </p>
+
+ <pre class="terminal">
+$ c++ -std=c++11 -I.../libxsd -c driver.cxx hello.cxx
+$ c++ -std=c++11 -o driver driver.o hello.o -lxerces-c
+$ ./driver hello.xml
+Hello, sun!
+Hello, moon!
+Hello, world!
+ </pre>
+
+ <p>Here <code>.../libxsd</code> represents the path to the
+ <a href="https://cppget.org/libxsd">libxsd</a> package root
+ directory. Note also that we are required to link our
+ application with the Xerces-C++ library because the generated
+ code uses it as the underlying XML parser.</p>
+
+ <h2><a name="2.5">2.5 Adding Serialization</a></h2>
+
+ <p>While parsing and accessing the XML data may be everything
+ you need, there are applications that require creating new
+ or modifying existing XML documents. By default XSD does
+ not produce serialization code. We will need to request
+ it with the <code>--generate-serialization</code> options:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --generate-serialization hello.xsd
+ </pre>
+
+ <p>If we now examine the generated <code>hello.hxx</code> file,
+ we will find a set of overloaded serialization functions,
+ including the following version:</p>
+
+ <pre class="c++">
+void
+hello (std::ostream&amp;,
+ const hello_t&amp;,
+ const xml_schema::namespace_infomap&amp; =
+ xml_schema::namespace_infomap ());
+
+ </pre>
+
+ <p>Just like with parsing functions, XSD generates serialization
+ functions for each global element unless instructed otherwise
+ with one of the <code>--root-element-*</code> options. For more
+ information on serialization functions see <a href="#6">Chapter 6,
+ "Serialization"</a>.</p>
+
+ <p>We first examine an application that modifies an existing
+ object model and serializes it back to XML:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ unique_ptr&lt;hello_t> h (hello (argv[1]));
+
+ // Change the greeting phrase.
+ //
+ h->greeting ("Hi");
+
+ // Add another entry to the name sequence.
+ //
+ h->name ().push_back ("mars");
+
+ // Serialize the modified object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "hello.xsd";
+
+ hello (cout, *h, map);
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>First, our application parses an XML document and obtains its
+ object model as in the previous example. Then it changes the
+ greeting string and adds another entry to the list of names.
+ Finally, it serializes the object model back to XML by calling
+ the serialization function.</p>
+
+ <p>The first argument we pass to the serialization function is
+ <code>cout</code> which results in the XML being written to
+ the standard output for us to inspect. We could have also
+ written the result to a file or memory buffer by creating an
+ instance of <code>std::ofstream</code> or <code>std::ostringstream</code>
+ and passing it instead of <code>cout</code>. The second argument is the
+ object model we want to serialize. The final argument is an optional
+ namespace information map for our vocabulary. It captures information
+ such as namespaces, namespace prefixes to which they should be mapped,
+ and schemas associated with these namespaces. If we don't provide
+ this argument then generic namespace prefixes (<code>p1</code>,
+ <code>p2</code>, etc.) will be automatically assigned to XML namespaces
+ and no schema information will be added to the resulting document
+ (see <a href="#6">Chapter 6, "Serialization"</a> for details).
+ In our case, the prefix (map key) and namespace name are empty
+ because our vocabulary does not use XML namespaces.</p>
+
+ <p>If we now compile and run this application we will see the
+ output as shown in the following listing:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hi&lt;/greeting>
+
+ &lt;name>sun&lt;/name>
+ &lt;name>moon&lt;/name>
+ &lt;name>world&lt;/name>
+ &lt;name>mars&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <p>We can also create and serialize an object model from scratch
+ as shown in the following example:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include &lt;fstream>
+#include "hello.hxx"
+
+using namespace std;
+
+int
+main (int argc, char* argv[])
+{
+ try
+ {
+ hello_t h ("Hi");
+
+ hello_t::name_sequence&amp; ns (h.name ());
+
+ ns.push_back ("Jane");
+ ns.push_back ("John");
+
+ // Serialize the object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "hello.xsd";
+
+ std::ofstream ofs (argv[1]);
+ hello (ofs, h, map);
+ }
+ catch (const xml_schema::exception&amp; e)
+ {
+ cerr &lt;&lt; e &lt;&lt; endl;
+ return 1;
+ }
+}
+ </pre>
+
+ <p>In this example we used the generated constructor to create
+ an instance of type <code>hello_t</code>. To reduce typing,
+ we obtained a reference to the name sequence which we then
+ used to add a few names. The serialization part is identical
+ to the previous example except this time we are writing to
+ a file. If we compile and run this program, it produces the
+ following XML file:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;hello xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="hello.xsd">
+
+ &lt;greeting>Hi&lt;/greeting>
+
+ &lt;name>Jane&lt;/name>
+ &lt;name>John&lt;/name>
+
+&lt;/hello>
+ </pre>
+
+ <h2><a name="2.6">2.6 Selecting Naming Convention</a></h2>
+
+ <p>By default XSD uses the so-called K&amp;R (Kernighan and Ritchie)
+ identifier naming convention in the generated code. 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 in the generated code for consistency.
+ XSD 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.</p>
+
+ <p>As an example, let's assume that our "Hello World" application
+ uses the so-called upper-camel-case naming convention for types
+ (that is, each word in a type name is capitalized) and the K&amp;R
+ convention for function names. Since K&amp;R is the default
+ convention for both type and function names, we only need to
+ change the type naming scheme:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --type-naming ucc hello.xsd
+ </pre>
+
+ <p>The <code>ucc</code> argument to the <code>--type-naming</code>
+ options stands for upper-camel-case. If we now examine the
+ generated <code>hello.hxx</code>, we will see the following
+ changes compared to the declarations shown in the previous
+ sections:</p>
+
+ <pre class="c++">
+class Hello_t
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::String GreetingType;
+
+ const GreetingType&amp;
+ greeting () const;
+
+ GreetingType&amp;
+ greeting ();
+
+ void
+ greeting (const GreetingType&amp; x);
+
+ // name
+ //
+ typedef xml_schema::String NameType;
+ typedef xsd::sequence&lt;NameType> NameSequence;
+ typedef NameSequence::iterator NameIterator;
+ typedef NameSequence::const_iterator NameConstIterator;
+
+ const NameSequence&amp;
+ name () const;
+
+ NameSequence&amp;
+ name ();
+
+ void
+ name (const NameSequence&amp; s);
+
+ // Constructor.
+ //
+ Hello_t (const GreetingType&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;Hello_t>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;Hello_t>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>Notice that the type names in the <code>xml_schema</code> namespace,
+ for example <code>xml_schema::String</code>, now also use the
+ upper-camel-case naming convention. The only thing that we may
+ be unhappy about in the above code is the <code>_t</code>
+ suffix in <code>Hello_t</code>. If we are not in a position
+ to change the schema, we can <em>touch-up</em> the <code>ucc</code>
+ convention with a custom translation rule using the
+ <code>--type-regex</code> option:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --type-naming ucc --type-regex '/ (.+)_t/\u$1/' hello.xsd
+ </pre>
+
+ <p>This results in the following changes to the generated code:</p>
+
+ <pre class="c++">
+class Hello
+{
+public:
+ // greeting
+ //
+ typedef xml_schema::String GreetingType;
+
+ const GreetingType&amp;
+ greeting () const;
+
+ GreetingType&amp;
+ greeting ();
+
+ void
+ greeting (const GreetingType&amp; x);
+
+ // name
+ //
+ typedef xml_schema::String NameType;
+ typedef xsd::sequence&lt;NameType> NameSequence;
+ typedef NameSequence::iterator NameIterator;
+ typedef NameSequence::const_iterator NameConstIterator;
+
+ const NameSequence&amp;
+ name () const;
+
+ NameSequence&amp;
+ name ();
+
+ void
+ name (const NameSequence&amp; s);
+
+ // Constructor.
+ //
+ Hello (const GreetingType&amp;);
+
+ ...
+
+};
+
+std::unique_ptr&lt;Hello>
+hello (const std::string&amp; uri);
+
+std::unique_ptr&lt;Hello>
+hello (std::istream&amp;);
+ </pre>
+
+ <p>For more detailed information on the <code>--type-naming</code>,
+ <code>--function-naming</code>, <code>--type-regex</code>, and
+ other <code>--*-regex</code> 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>
+
+ <h2><a name="2.7">2.7 Generating Documentation</a></h2>
+
+ <p>While our object model is quite simple, real-world vocabularies
+ can be quite complex with hundreds of types, elements, and
+ attributes. For such vocabularies figuring out which types
+ provide which member functions by studying the generated
+ source code or schemas can be a daunting task. To provide
+ application developers with a more accessible way of
+ understanding the generated object models, the XSD compiler
+ can be instructed to produce source code with documentation
+ comments in the Doxygen format. Then the source code can be
+ processed with the <a href="http://www.doxygen.org">Doxygen</a>
+ documentation system to extract this information and produce
+ documentation in various formats.
+ </p>
+
+ <p>In this section we will see how to generate documentation
+ for our "Hello World" vocabulary. To showcase the full power
+ of the XSD documentation facilities, we will first document
+ our schema. The XSD compiler will then transfer
+ this information from the schema to the generated code and
+ then to the object model documentation. Note that the
+ documentation in the schema is not required for XSD to
+ generate useful documentation. Below you will find
+ our <code>hello.xsd</code> with added documentation:</p>
+
+ <pre class="xml">
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:complexType name="hello_t">
+
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The hello_t type consists of a greeting phrase and a
+ collection of names to which this greeting applies.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+
+ &lt;xs:sequence>
+
+ &lt;xs:element name="greeting" type="xs:string">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The greeting element contains the greeting phrase
+ for this hello object.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+ &lt;xs:element name="name" type="xs:string" maxOccurs="unbounded">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The name elements contains names to be greeted.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="hello" type="hello_t">
+ &lt;xs:annotation>
+ &lt;xs:documentation>
+ The hello element is a root of the Hello XML vocabulary.
+ Every conforming document should start with this element.
+ &lt;/xs:documentation>
+ &lt;/xs:annotation>
+ &lt;/xs:element>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>The first step in obtaining the documentation is to recompile
+ our schema with the <code>--generate-doxygen</code> option:</p>
+
+ <pre class="terminal">
+$ xsd cxx-tree --generate-serialization --generate-doxygen hello.xsd
+ </pre>
+
+ <p>Now the generated <code>hello.hxx</code> file contains comments
+ in the Doxygen format. The next step is to process this file
+ with the Doxygen documentation system. If your project does
+ not use Doxygen then you first need to create a configuration
+ file for your project:</p>
+
+ <pre class="terminal">
+$ doxygen -g hello.doxygen
+ </pre>
+
+ <p>You only need to perform this step once. Now we can generate
+ the documentation by executing the following command in the
+ directory with the generated source code:</p>
+
+ <pre class="terminal">
+$ doxygen hello.doxygen
+ </pre>
+
+ <p>While the generated documentation can be useful as is, we can
+ go one step further and link (using the Doxygen tags mechanism)
+ the documentation for our object model with the documentation
+ for the XSD runtime library which defines C++ classes for the
+ built-in XML Schema types. This way we can seamlessly browse
+ between documentation for the <code>hello_t</code> class which
+ is generated by the XSD compiler and the <code>xml_schema::string</code>
+ class which is defined in the XSD runtime library. The Doxygen
+ configuration file for the XSD runtime is provided with the XSD
+ distribution.</p>
+
+ <p>You can view the result of the steps described in this section
+ on the <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/hello/html/annotated.html">Hello
+ Example Documentation</a> page.</p>
+
+ <!-- Chapater 3 -->
+
+
+ <h1><a name="3">3 Overall Mapping Configuration</a></h1>
+
+ <p>The C++/Tree mapping has a number of configuration parameters that
+ determine the overall properties and behavior of the generated code.
+ Configuration parameters are specified with the XSD command line
+ options. This chapter describes configuration aspects that are most
+ commonly encountered by application developers. These include: the
+ C++ standard, the character type that is used by the generated code,
+ handling of vocabularies that use XML Schema polymorphism, XML Schema
+ to C++ namespace mapping, and thread safety. For more ways to configure
+ the generated code refer to the
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/xsd.xhtml">XSD
+ Compiler Command Line Manual</a>.
+ </p>
+
+ <h2><a name="3.1">3.1 C++ Standard</a></h2>
+
+ <p>The C++/Tree mapping provides support for ISO/IEC C++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</p>
+
+ <h2><a name="3.2">3.2 Character Type and Encoding</a></h2>
+
+ <p>The C++/Tree mapping has built-in support for two character types:
+ <code>char</code> and <code>wchar_t</code>. You can select the
+ character type with the <code>--char-type</code> command line
+ option. The default character type is <code>char</code>. The
+ character type affects all string and string-based types that
+ are used in the mapping. These include the string-based built-in
+ XML Schema types, exception types, stream types, etc.</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. You can select which encoding should be used
+ in the object model 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>
+
+ <p>Note also that the character encoding that is used in the object model
+ is independent of the encodings used in input and output XML. In fact,
+ all three (object mode, input XML, and output XML) can have different
+ encodings.</p>
+
+ <h2><a name="3.3">3.3 Support for Polymorphism</a></h2>
+
+ <p>By default XSD generates non-polymorphic code. If your vocabulary
+ uses XML Schema polymorphism in the form of <code>xsi:type</code>
+ and/or substitution groups, then you will need to compile
+ your schemas with the <code>--generate-polymorphic</code> option
+ to produce polymorphism-aware code. For more information on
+ working with polymorphic object models, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.11">Section 2.11,
+ "Mapping for <code>xsi:type</code> and Substitution Groups"</a> in
+ the C++/Tree Mapping User Manual.</p>
+
+ <h2><a name="3.4">3.4 Namespace Mapping</a></h2>
+
+ <p>XSD maps XML namespaces specified in the <code>targetNamespace</code>
+ attribute in XML Schema to one or more nested C++ namespaces. 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.</p>
+
+ <p>The default mapping of namespace URIs to C++ namespaces
+ can be altered using the <code>--namespace-map</code> and
+ <code>--namespace-regex</code> compiler options. For example,
+ to map namespace URI <code>https://www.codesynthesis.com/my</code> to
+ C++ namespace <code>cs::my</code>, we can use the following option:</p>
+
+ <pre class="terminal">
+--namespace-map https://www.codesynthesis.com/my=cs::my
+ </pre>
+
+ <p>A vocabulary without a namespace is mapped to the global scope. This
+ also can be altered with the above options by using an empty name
+ for the XML namespace:</p>
+
+ <pre class="terminal">
+--namespace-map =cs
+ </pre>
+
+ <h2><a name="3.5">3.5 Thread Safety</a></h2>
+
+ <p>XSD-generated code is thread-safe in the sense that you can
+ use different instantiations of the object model in several
+ threads concurrently. This is possible due to the generated
+ code not relying on any writable global variables. If you need
+ to share the same object between several threads then you will
+ need to provide some form of synchronization. One approach would
+ be to use the generated code customization mechanisms to embed
+ synchronization primitives into the generated C++ classes. For more
+ information on generated code customization refer to the
+ <a href="http://wiki.codesynthesis.com/Tree/Customization_guide">C++/Tree
+ Mapping Customization Guide</a>.</p>
+
+ <p>If you also would like to call parsing and/or serialization
+ functions from several threads potentially concurrently, then
+ you will need to make sure the Xerces-C++ runtime is initialized
+ and terminated only once. The easiest way to do this is to
+ initialize/terminate Xerces-C++ from <code>main()</code> when
+ there are no threads yet/anymore:</p>
+
+ <pre class="c++">
+#include &lt;xercesc/util/PlatformUtils.hpp>
+
+int
+main ()
+{
+ xercesc::XMLPlatformUtils::Initialize ();
+
+ {
+ // Start/terminate threads and parse/serialize here.
+ }
+
+ xercesc::XMLPlatformUtils::Terminate ();
+}
+ </pre>
+
+ <p>Because you initialize the Xerces-C++ runtime yourself you should
+ also pass the <code>xml_schema::flags::dont_initialize</code> flag
+ to parsing and serialization functions. See <a href="#5">Chapter 5,
+ "Parsing"</a> and <a href="#6">Chapter 6, "Serialization"</a> for
+ more information.</p>
+
+
+ <!-- Chapater 4 -->
+
+
+ <h1><a name="4">4 Working with Object Models</a></h1>
+
+ <p>As we have seen in the previous chapters, the XSD compiler generates
+ a C++ class for each type defined in XML Schema. Together these classes
+ constitute an object model for an XML vocabulary. In this chapter we
+ will take a closer look at different elements that comprise an
+ object model class as well as how to create, access, and modify
+ object models.</p>
+
+ <p>In this and subsequent chapters we will use the following schema
+ that describes a collection of person records. We save it in
+ <code>people.xsd</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ &lt;xs:simpleType name="gender_t">
+ &lt;xs:restriction base="xs:string">
+ &lt;xs:enumeration value="male"/>
+ &lt;xs:enumeration value="female"/>
+ &lt;/xs:restriction>
+ &lt;/xs:simpleType>
+
+ &lt;xs:complexType name="person_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="first-name" type="xs:string"/>
+ &lt;xs:element name="middle-name" type="xs:string" minOccurs="0"/>
+ &lt;xs:element name="last-name" type="xs:string"/>
+ &lt;xs:element name="gender" type="gender_t"/>
+ &lt;xs:element name="age" type="xs:short"/>
+ &lt;/xs:sequence>
+ &lt;xs:attribute name="id" type="xs:unsignedInt" use="required"/>
+ &lt;/xs:complexType>
+
+ &lt;xs:complexType name="people_t">
+ &lt;xs:sequence>
+ &lt;xs:element name="person" type="person_t" maxOccurs="unbounded"/>
+ &lt;/xs:sequence>
+ &lt;/xs:complexType>
+
+ &lt;xs:element name="people" type="people_t"/>
+
+&lt;/xs:schema>
+ </pre>
+
+ <p>A sample XML instance to go along with this schema is saved
+ in <code>people.xml</code>:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+ <p>Compiling <code>people.xsd</code> with the XSD compiler results
+ in three generated C++ classes: <code>gender_t</code>,
+ <code>person_t</code>, and <code>people_t</code>.
+ The <code>gender_t</code> class is modelled after the C++
+ <code>enum</code> type. Its definition is presented below:</p>
+
+ <pre class="c++">
+class gender_t: public xml_schema::string
+{
+public:
+ enum value
+ {
+ male,
+ female
+ };
+
+ gender_t (value);
+ gender_t (const xml_schema::string&amp;);
+
+ gender_t&amp;
+ operator= (value);
+
+ operator value () const;
+};
+ </pre>
+
+ <p>The following listing shows how we can use this type:</p>
+
+ <pre class="c++">
+gender_t m (gender_t::male);
+gender_t f ("female");
+
+if (m == "female" || f == gender_t::male)
+{
+ ...
+}
+
+switch (m)
+{
+case gender_t::male:
+ {
+ ...
+ }
+case gender_t::female:
+ {
+ ...
+ }
+}
+ </pre>
+
+ <p>The other two classes will be examined in detail in the subsequent
+ sections.</p>
+
+ <h2><a name="4.1">4.1 Attribute and Element Cardinalities</a></h2>
+
+ <p>As we have seen in the previous chapters, XSD generates a different
+ set of type definitions and member functions for elements with
+ different cardinalities. The C++/Tree mapping divides all the possible
+ element and attribute cardinalities into three cardinality classes:
+ <em>one</em>, <em>optional</em>, and <em>sequence</em>.</p>
+
+ <p>The <em>one</em> cardinality class covers all elements that should
+ occur exactly once as well as required attributes. In our
+ example, the <code>first-name</code>, <code>last-name</code>,
+ <code>gender</code>, and <code>age</code> elements as well as
+ the <code>id</code> attribute belong to this cardinality class.
+ The following code fragment shows type definitions as well as the
+ accessor and modifier functions that are generated for the
+ <code>gender</code> element in the <code>person_t</code> class:</p>
+
+ <pre class="c++">
+class person_t
+{
+ // gender
+ //
+ typedef gender_t gender_type;
+
+ const gender_type&amp;
+ gender () const;
+
+ gender_type&amp;
+ gender ();
+
+ void
+ gender (const gender_type&amp;);
+};
+ </pre>
+
+ <p>The <code>gender_type</code> type is an alias for the element's type.
+ The first two accessor functions return read-only (constant) and
+ read-write references to the element's value, respectively. The
+ modifier function sets the new value for the element.</p>
+
+ <p>The <em>optional</em> cardinality class covers all elements that
+ can occur zero or one time as well as optional attributes. In our
+ example, the <code>middle-name</code> element belongs to this
+ cardinality class. The following code fragment shows the type
+ definitions as well as the accessor and modifier functions that
+ are generated for this element in the <code>person_t</code> class:</p>
+
+ <pre class="c++">
+class person_t
+{
+ // middle-name
+ //
+ typedef xml_schema::string middle_name_type;
+ typedef xsd::optional&lt;middle_name_type> middle_name_optional;
+
+ const middle_name_optional&amp;
+ middle_name () const;
+
+ middle_name_optional&amp;
+ middle_name ();
+
+ void
+ middle_name (const middle_name_type&amp;);
+
+ void
+ middle_name (const middle_name_optional&amp;);
+};
+ </pre>
+
+ <p>As with the <code>gender</code> element, <code>middle_name_type</code>
+ is an alias for the element's type. The <code>middle_name_optional</code>
+ type is a container for the element's optional value. It can be queried
+ for the presence of the value using the <code>present()</code> function.
+ The value itself can be retrieved using the <code>get()</code>
+ accessor and set using the <code>set()</code> modifier. The container
+ can be reverted to the value not present state with the call to the
+ <code>reset()</code> function. The following example shows how we
+ can use this container:</p>
+
+ <pre class="c++">
+person_t::middle_name_optional n ("John");
+
+if (n.present ())
+{
+ cout &lt;&lt; n.get () &lt;&lt; endl;
+}
+
+n.set ("Jane");
+n.reset ();
+ </pre>
+
+
+ <p>Unlike the <em>one</em> cardinality class, the accessor functions
+ for the <em>optional</em> class return read-only (constant) and
+ read-write references to the container instead of the element's
+ value directly. The modifier functions set the new value for the
+ element.</p>
+
+ <p>Finally, the <em>sequence</em> cardinality class covers all elements
+ that can occur more than once. In our example, the
+ <code>person</code> element in the <code>people_t</code> type
+ belongs to this cardinality class. The following code fragment shows
+ the type definitions as well as the accessor and modifier functions
+ that are generated for this element in the <code>people_t</code>
+ class:</p>
+
+ <pre class="c++">
+class people_t
+{
+ // person
+ //
+ typedef person_t person_type;
+ typedef xsd::sequence&lt;person_type> person_sequence;
+ typedef person_sequence::iterator person_iterator;
+ typedef person_sequence::const_iterator person_const_iterator;
+
+ const person_sequence&amp;
+ person () const;
+
+ person_sequence&amp;
+ person ();
+
+ void
+ person (const person_sequence&amp;);
+};
+ </pre>
+
+ <p>Identical to the other cardinality classes, <code>person_type</code>
+ is an alias for the element's type. The <code>person_sequence</code>
+ type is a sequence container for the element's values. It is based
+ on and has the same interface as <code>std::vector</code> and
+ therefore can be used in similar ways. The <code>person_iterator</code>
+ and <code>person_const_iterator</code> types are read-only
+ (constant) and read-write iterators for the <code>person_sequence</code>
+ container.</p>
+
+ <p>Similar to the <em>optional</em> cardinality class, the
+ accessor functions for the <em>sequence</em> class return
+ read-only (constant) and read-write references to the sequence
+ container. The modifier functions copies the entries from
+ the passed sequence.</p>
+
+ <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 above. 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. To
+ overcome this limitation we can mark certain schema types, for which
+ content order is not sufficiently preserved, as ordered. For more
+ information on this functionality refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.8.4">Section
+ 2.8.4, "Element Order"</a> in the C++/Tree Mapping User Manual.</p>
+
+ <p>For complex schemas with many levels of nested compositors
+ (<code>choice</code> and <code>sequence</code>) it can also
+ be hard to deduce the cardinality class of a particular element.
+ The generated Doxygen documentation can greatly help with
+ this task. For each element and attribute the documentation
+ clearly identifies its cardinality class. Alternatively, you
+ can study the generated header files to find out the cardinality
+ class of a particular attribute or element.</p>
+
+ <p>In the next sections we will examine how to access and modify
+ information stored in an object model using accessor and modifier
+ functions described in this section.</p>
+
+ <h2><a name="4.2">4.2 Accessing the Object Model</a></h2>
+
+ <p>In this section we will learn how to get to the information
+ stored in the object model for our person records vocabulary.
+ The following application accesses and prints the contents
+ of the <code>people.xml</code> file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ unique_ptr&lt;people_t> ppl (people ("people.xml"));
+
+ // Iterate over individual person records.
+ //
+ people_t::person_sequence&amp; ps (ppl->person ());
+
+ for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
+ {
+ person_t&amp; p (*i);
+
+ // Print names: first-name and last-name are required elements,
+ // middle-name is optional.
+ //
+ cout &lt;&lt; "name: " &lt;&lt; p.first_name () &lt;&lt; " ";
+
+ if (p.middle_name ().present ())
+ cout &lt;&lt; p.middle_name ().get () &lt;&lt; " ";
+
+ cout &lt;&lt; p.last_name () &lt;&lt; endl;
+
+ // Print gender, age, and id which are all required.
+ //
+ cout &lt;&lt; "gender: " &lt;&lt; p.gender () &lt;&lt; endl
+ &lt;&lt; "age: " &lt;&lt; p.age () &lt;&lt; endl
+ &lt;&lt; "id: " &lt;&lt; p.id () &lt;&lt; endl
+ &lt;&lt; endl;
+ }
+}
+ </pre>
+
+ <p>This code shows common patterns of accessing elements and attributes
+ with different cardinality classes. For the sequence element
+ (<code>person</code> in <code>people_t</code>) we first obtain a
+ reference to the container and then iterate over individual
+ records. The values of elements and attributes with the
+ <em>one</em> cardinality class (<code>first-name</code>,
+ <code>last-name</code>, <code>gender</code>, <code>age</code>,
+ and <code>id</code>) can be obtained directly by calling the
+ corresponding accessor functions. For the optional element
+ <code>middle-name</code> we first check if the value is present
+ and only then call <code>get()</code> to retrieve it.</p>
+
+ <p>Note that when we want to reduce typing by creating a variable
+ representing a fragment of the object model that we are currently
+ working with (<code>ps</code> and <code>p</code> above), we obtain
+ a reference to that fragment instead of making a potentially
+ expensive copy. This is generally a good rule to follow when
+ creating high-performance applications.</p>
+
+ <p>If we run the above application on our sample
+ <code>people.xml</code>, the output looks as follows:</p>
+
+ <pre class="terminal">
+name: John Doe
+gender: male
+age: 32
+id: 1
+
+name: Jane Mary Doe
+gender: female
+age: 28
+id: 2
+ </pre>
+
+
+ <h2><a name="4.3">4.3 Modifying the Object Model</a></h2>
+
+ <p>In this section we will learn how to modify the information
+ stored in the object model for our person records vocabulary.
+ The following application changes the contents of the
+ <code>people.xml</code> file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ unique_ptr&lt;people_t> ppl (people ("people.xml"));
+
+ // Iterate over individual person records and increment
+ // the age.
+ //
+ people_t::person_sequence&amp; ps (ppl->person ());
+
+ for (people_t::person_iterator i (ps.begin ()); i != ps.end (); ++i)
+ {
+ // Alternative way: i->age ()++;
+ //
+ i->age (i->age () + 1);
+ }
+
+ // Add middle-name to the first record and remove it from
+ // the second.
+ //
+ person_t&amp; john (ps[0]);
+ person_t&amp; jane (ps[1]);
+
+ john.middle_name ("Mary");
+ jane.middle_name ().reset ();
+
+ // Add another John record.
+ //
+ ps.push_back (john);
+
+ // Serialize the modified object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "people.xsd";
+
+ people (cout, *ppl, map);
+}
+ </pre>
+
+ <p>The first modification the above application performs is iterating
+ over person records and incrementing the age value. This code
+ fragment shows how to modify the value of a required attribute
+ or element. The next modification shows how to set a new value
+ for the optional <code>middle-name</code> element as well
+ as clear its value. Finally the example adds a copy of the
+ John Doe record to the <code>person</code> element sequence.</p>
+
+ <p>Note that in this case using references for the <code>ps</code>,
+ <code>john</code>, and <code>jane</code> variables is no longer
+ a performance improvement but a requirement for the application
+ to function correctly. If we hadn't used references, all our changes
+ would have been made on copies without affecting the object model.</p>
+
+ <p>If we run the above application on our sample <code>people.xml</code>,
+ the output looks as follows:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0"?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>33&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>29&lt;/age>
+ &lt;/person>
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>33&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+
+ <h2><a name="4.4">4.4 Creating the Object Model from Scratch</a></h2>
+
+ <p>In this section we will learn how to create a new object model
+ for our person records vocabulary. The following application
+ recreates the content of the original <code>people.xml</code>
+ file:</p>
+
+ <pre class="c++">
+#include &lt;iostream>
+#include "people.hxx"
+
+using namespace std;
+
+int
+main ()
+{
+ people_t ppl;
+ people_t::person_sequence&amp; ps (ppl.person ());
+
+ // Add the John Doe record.
+ //
+ ps.push_back (
+ person_t ("John", // first-name
+ "Doe", // last-name
+ gender_t::male, // gender
+ 32, // age
+ 1));
+
+ // Add the Jane Doe record.
+ //
+ ps.push_back (
+ person_t ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2)); // id
+
+ // Add middle name to the Jane Doe record.
+ //
+ person_t&amp; jane (ps.back ());
+ jane.middle_name ("Mary");
+
+ // Serialize the object model to XML.
+ //
+ xml_schema::namespace_infomap map;
+ map[""].name = "";
+ map[""].schema = "people.xsd";
+
+ people (cout, ppl, map);
+}
+ </pre>
+
+ <p>The only new part in the above application is the calls
+ to the <code>people_t</code> and <code>person_t</code>
+ constructors. As a general rule, for each C++ class
+ XSD generates a constructor with initializers
+ for each element and attribute belonging to the <em>one</em>
+ cardinality class. For our vocabulary, the following
+ constructors are generated:</p>
+
+ <pre class="c++">
+class person_t
+{
+ person_t (const first_name_type&amp;,
+ const last_name_type&amp;,
+ const gender_type&amp;,
+ const age_type&amp;,
+ const id_type&amp;);
+};
+
+class people_t
+{
+ people_t ();
+};
+ </pre>
+
+ <p>Note also that we set the <code>middle-name</code> element
+ on the Jane Doe record by obtaining a reference to that record
+ in the object model and setting the <code>middle-name</code>
+ value on it. This is a general rule that should be followed
+ in order to obtain the best performance: if possible,
+ direct modifications to the object model should be preferred
+ to modifications on temporaries with subsequent copying. The
+ following code fragment shows a semantically equivalent but
+ slightly slower version:</p>
+
+ <pre class="c++">
+// Add the Jane Doe record.
+//
+person_t jane ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2); // id
+
+jane.middle_name ("Mary");
+
+ps.push_back (jane);
+ </pre>
+
+ <p>We can also go one step further to reduce copying and improve
+ the performance of our application by using the non-copying
+ <code>push_back()</code> function which assumes ownership
+ of the passed objects:</p>
+
+ <pre class="c++">
+// Add the Jane Doe record. C++11 version
+//
+unique_ptr&lt;person_t> jane_p (
+ new person_t ("Jane", // first-name
+ "Doe", // last-name
+ gender_t::female, // gender
+ 28, // age
+ 2)); // id
+ps.push_back (std::move (jane_p)); // assumes ownership
+
+// Add the John Doe record. C++98 version.
+//
+auto_ptr&lt;person_t> john_p (
+ new person_t ("John", // first-name
+ "Doe", // last-name
+ gender_t::male, // gender
+ 32, // age
+ 1));
+ps.push_back (john_p); // assumes ownership
+ </pre>
+
+ <p>For more information on the non-copying modifier functions refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.8">Section
+ 2.8, "Mapping for Local Elements and Attributes"</a> in the C++/Tree Mapping
+ User Manual. The above application produces the following output:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd">
+
+ &lt;person id="1">
+ &lt;first-name>John&lt;/first-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>male&lt;/gender>
+ &lt;age>32&lt;/age>
+ &lt;/person>
+
+ &lt;person id="2">
+ &lt;first-name>Jane&lt;/first-name>
+ &lt;middle-name>Mary&lt;/middle-name>
+ &lt;last-name>Doe&lt;/last-name>
+ &lt;gender>female&lt;/gender>
+ &lt;age>28&lt;/age>
+ &lt;/person>
+
+&lt;/people>
+ </pre>
+
+ <h2><a name="4.5">4.5 Mapping for the Built-in XML Schema Types</a></h2>
+
+ <p>Our person record vocabulary uses several built-in XML Schema
+ types: <code>string</code>, <code>short</code>, and
+ <code>unsignedInt</code>. Until now we haven't talked about
+ the mapping of built-in XML Schema types to C++ types and how
+ to work with them. This section provides an overview
+ of the built-in types. For more detailed information refer
+ to <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.5">Section
+ 2.5, "Mapping for Built-in Data Types"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>In XML Schema, built-in types are defined in the XML Schema namespace.
+ By default, the C++/Tree mapping maps this namespace to C++
+ namespace <code>xml_schema</code> (this mapping can be altered
+ with the <code>--namespace-map</code> option). The following table
+ summarizes the mapping of XML Schema built-in types to C++ types:</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">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><code>xml_schema::qname</code></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>type derived from <code>ncname</code></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><code>xml_schema::base64_binary</code></td>
+ </tr>
+ <tr>
+ <td><code>hexBinary</code></td>
+ <td><code>hex_binary</code></td>
+ <td><code>xml_schema::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><code>xml_schema::date</code></td>
+ </tr>
+ <tr>
+ <td><code>dateTime</code></td>
+ <td><code>date_time</code></td>
+ <td><code>xml_schema::date_time</code></td>
+ </tr>
+ <tr>
+ <td><code>duration</code></td>
+ <td><code>duration</code></td>
+ <td><code>xml_schema::duration</code></td>
+ </tr>
+ <tr>
+ <td><code>gDay</code></td>
+ <td><code>gday</code></td>
+ <td><code>xml_schema::gday</code></td>
+ </tr>
+ <tr>
+ <td><code>gMonth</code></td>
+ <td><code>gmonth</code></td>
+ <td><code>xml_schema::gmonth</code></td>
+ </tr>
+ <tr>
+ <td><code>gMonthDay</code></td>
+ <td><code>gmonth_day</code></td>
+ <td><code>xml_schema::gmonth_day</code></td>
+ </tr>
+ <tr>
+ <td><code>gYear</code></td>
+ <td><code>gyear</code></td>
+ <td><code>xml_schema::gyear</code></td>
+ </tr>
+ <tr>
+ <td><code>gYearMonth</code></td>
+ <td><code>gyear_month</code></td>
+ <td><code>xml_schema::gyear_month</code></td>
+ </tr>
+ <tr>
+ <td><code>time</code></td>
+ <td><code>time</code></td>
+ <td><code>xml_schema::time</code></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>As you can see from the table above a number of built-in
+ XML Schema types are mapped to fundamental C++ types such
+ as <code>int</code> or <code>bool</code>. All string-based
+ XML Schema types are mapped to C++ types that are derived
+ from either <code>std::string</code> or
+ <code>std::wstring</code>, depending on the character
+ type selected. For access and modification purposes these
+ types can be treated as <code>std::string</code>. A number
+ of built-in types, such as <code>qname</code>, the binary
+ types, and the date/time types do not have suitable
+ fundamental or standard C++ types to map to. As a result,
+ these types are implemented from scratch in the XSD runtime.
+ For more information on their interfaces refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.5">Section
+ 2.5, "Mapping for Built-in Data Types"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+
+ <!-- Chapater 5 -->
+
+
+ <h1><a name="5">5 Parsing</a></h1>
+
+ <p>We have already seen how to parse XML to an object model in this guide
+ before. In this chapter we will discuss the parsing topic in more
+ detail.</p>
+
+ <p>By default, the C++/Tree mapping provides a total of 14 overloaded
+ parsing functions. They differ in the input methods used to
+ read XML as well as the error reporting mechanisms. It is also possible
+ to generate types for root elements instead of parsing and serialization
+ functions. This may be useful if your XML vocabulary has multiple
+ root elements. For more information on element types refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.9">Section
+ 2.9, "Mapping for Global Elements"</a> in the C++/Tree Mapping User
+ Manual.</p>
+
+
+ <p>In this section we will discuss the most commonly used versions of
+ the parsing functions. For a comprehensive description of parsing
+ refer to <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#3">Chapter
+ 3, "Parsing"</a> in the C++/Tree Mapping User Manual. For the <code>people</code>
+ global element from our person record vocabulary, we will concentrate
+ on the following three parsing functions:</p>
+
+ <pre class="c++">
+std::[unique|auto]_ptr&lt;people_t>
+people (const std::string&amp; uri,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;people_t>
+people (std::istream&amp; is,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;people_t>
+people (std::istream&amp; is,
+ const std::string&amp; resource_id,
+ xml_schema::flags f = 0,
+ const xml_schema::properties&amp; p = ::xml_schema::properties ());
+ </pre>
+
+ <p>The first function parses a local file or a URI. We have already
+ used this parsing function in the previous chapters. The second
+ and third functions read XML from a standard input stream. The
+ last function also requires a resource id. This id is used to
+ identify the XML document being parser in diagnostics messages
+ as well as to resolve relative paths to other documents (for example,
+ schemas) that might be referenced from the XML document.</p>
+
+ <p>The last two arguments to all three parsing functions are parsing
+ flags and properties. The flags argument provides a number of ways
+ to fine-tune the parsing process. The properties argument allows
+ to pass additional information to the parsing functions. We will
+ use these two arguments in <a href="#5.1">Section 5.1, "XML Schema
+ Validation and Searching"</a> below. All three functions return
+ the object model as either <code>std::unique_ptr</code> (C++11) or
+ <code>std::auto_ptr</code> (C++98), depending on the C++ standard
+ selected (<code>--std</code> XSD compiler option). The following
+ example shows how we can use the above parsing functions:</p>
+
+ <pre class="c++">
+using std::unique_ptr;
+
+// Parse a local file or URI.
+//
+unique_ptr&lt;people_t> p1 (people ("people.xml"));
+unique_ptr&lt;people_t> p2 (people ("http://example.com/people.xml"));
+
+// Parse a local file via ifstream.
+//
+std::ifstream ifs ("people.xml");
+unique_ptr&lt;people_t> p3 (people (ifs, "people.xml"));
+
+// Parse an XML string.
+//
+std::string str ("..."); // XML in a string.
+std::istringstream iss (str);
+unique_ptr&lt;people_t> p4 (people (iss));
+ </pre>
+
+
+ <h2><a name="5.1">5.1 XML Schema Validation and Searching</a></h2>
+
+ <p>The C++/Tree mapping relies on the underlying Xerces-C++ XML
+ parser for full XML document validation. The XML Schema
+ validation is enabled by default and can be disabled by
+ passing the <code>xml_schema::flags::dont_validate</code>
+ flag to the parsing functions, for example:</p>
+
+ <pre class="c++">
+unique_ptr&lt;people_t> p (
+ people ("people.xml", xml_schema::flags::dont_validate));
+ </pre>
+
+ <p>Even when XML Schema validation is disabled, the generated
+ code still performs a number of checks to prevent
+ construction of an inconsistent object model (for example, an
+ object model with missing required attributes or elements).</p>
+
+ <p>When XML Schema validation is enabled, the XML parser needs
+ to locate a schema to validate against. There are several
+ methods to provide the schema location information to the
+ parser. The easiest and most commonly used method is to
+ specify schema locations in the XML document itself
+ with the <code>schemaLocation</code> or
+ <code>noNamespaceSchemaLocation</code> attributes, for example:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;people xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="people.xsd"
+ xsi:schemaLocation="http://www.w3.org/XML/1998/namespace xml.xsd">
+ </pre>
+
+ <p>As you might have noticed, we used this method in all the sample XML
+ documents presented in this guide up until now. Note that the
+ schema locations specified with these two attributes are relative
+ to the document's path unless they are absolute URIs (that is
+ start with <code>http://</code>, <code>file://</code>, etc.).
+ In particular, if you specify just file names as your schema
+ locations, as we did above, then the schemas should reside in
+ the same directory as the XML document itself.</p>
+
+ <p>Another method of providing the schema location information
+ is via the <code>xml_schema::properties</code> argument, as
+ shown in the following example:</p>
+
+ <pre class="c++">
+xml_schema::properties props;
+props.no_namespace_schema_location ("people.xsd");
+props.schema_location ("http://www.w3.org/XML/1998/namespace", "xml.xsd");
+
+unique_ptr&lt;people_t> p (people ("people.xml", 0, props));
+ </pre>
+
+ <p>The schema locations provided with this method overrides
+ those specified in the XML document. As with the previous
+ method, the schema locations specified this way are
+ relative to the document's path unless they are absolute URIs.
+ In particular, if you want to use local schemas that are
+ not related to the document being parsed, then you will
+ need to use the <code>file://</code> URI. The following
+ example shows how to use schemas that reside in the current
+ working directory:</p>
+
+ <pre class="c++">
+#include &lt;unistd.h> // getcwd
+#include &lt;limits.h> // PATH_MAX
+
+char cwd[PATH_MAX];
+if (getcwd (cwd, PATH_MAX) == 0)
+{
+ // Buffer too small?
+}
+
+xml_schema::properties props;
+
+props.no_namespace_schema_location (
+ "file:///" + std::string (cwd) + "/people.xsd");
+
+props.schema_location (
+ "http://www.w3.org/XML/1998/namespace",
+ "file:///" + std::string (cwd) + "/xml.xsd");
+
+unique_ptr&lt;people_t> p (people ("people.xml", 0, props));
+ </pre>
+
+ <p>A third method is the most useful if you are planning to parse
+ several XML documents of the same vocabulary. In that case
+ it may be beneficial to pre-parse and cache the schemas in
+ the XML parser which can then be used to parse all documents
+ without re-parsing the schemas. For more information on
+ this method refer to the <code>caching</code> example in the
+ <code>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package.
+ It is also possible to convert the schemas into a pre-compiled
+ binary representation and embed this representation directly into
+ the application executable. With this approach your application can
+ perform XML Schema validation without depending on any external
+ schema files. For more information on how to achieve this refer to
+ the <code>embedded</code> example in the <code>cxx/tree/</code>
+ directory in the <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</p>
+
+ <p>When the XML parser cannot locate a schema for the
+ XML document, the validation fails and XML document
+ elements and attributes for which schema definitions could
+ not be located are reported in the diagnostics. For
+ example, if we remove the <code>noNamespaceSchemaLocation</code>
+ attribute in <code>people.xml</code> from the previous chapter,
+ then we will get the following diagnostics if we try to parse
+ this file with validation enabled:</p>
+
+ <pre class="terminal">
+people.xml:2:63 error: no declaration found for element 'people'
+people.xml:4:18 error: no declaration found for element 'person'
+people.xml:4:18 error: attribute 'id' is not declared for element 'person'
+people.xml:5:17 error: no declaration found for element 'first-name'
+people.xml:6:18 error: no declaration found for element 'middle-name'
+people.xml:7:16 error: no declaration found for element 'last-name'
+people.xml:8:13 error: no declaration found for element 'gender'
+people.xml:9:10 error: no declaration found for element 'age'
+ </pre>
+
+ <h2><a name="5.2">5.2 Error Handling</a></h2>
+
+ <p>The parsing functions offer a number of ways to handle error conditions
+ with the C++ exceptions being the most commonly used mechanism. All
+ C++/Tree exceptions derive from common base <code>xml_schema::exception</code>
+ which in turn derives from <code>std::exception</code>. The easiest
+ way to uniformly handle all possible C++/Tree exceptions and print
+ detailed information about the error is to catch and print
+ <code>xml_schema::exception</code>, as shown in the following
+ example:</p>
+
+ <pre class="c++">
+try
+{
+ unique_ptr&lt;people_t> p (people ("people.xml"));
+}
+catch (const xml_schema::exception&amp; e)
+{
+ cerr &lt;&lt; e &lt;&lt; endl;
+}
+ </pre>
+
+ <p>Each individual C++/Tree exception also allows you to obtain
+ error details programmatically. For example, the
+ <code>xml_schema::parsing</code> exception is thrown when
+ the XML parsing and validation in the underlying XML parser
+ fails. It encapsulates various diagnostics information
+ such as the file name, line and column numbers, as well as the
+ error or warning message for each entry. For more information
+ about this and other exceptions that can be thrown during
+ parsing, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#3.3">Section
+ 3.3, "Error Handling"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>Note that if you are parsing <code>std::istream</code> on which
+ exceptions are not enabled, then you will need to check the
+ stream state after the call to the parsing function in order
+ to detect any possible stream failures, for example:</p>
+
+ <pre class="c++">
+std::ifstream ifs ("people.xml");
+
+if (ifs.fail ())
+{
+ cerr &lt;&lt; "people.xml: unable to open" &lt;&lt; endl;
+ return 1;
+}
+
+unique_ptr&lt;people_t> p (people (ifs, "people.xml"));
+
+if (ifs.fail ())
+{
+ cerr &lt;&lt; "people.xml: read error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions as
+ shown below:</p>
+
+ <pre class="c++">
+try
+{
+ std::ifstream ifs;
+ ifs.exceptions (std::ifstream::badbit | std::ifstream::failbit);
+ ifs.open ("people.xml");
+
+ unique_ptr&lt;people_t> p (people (ifs, "people.xml"));
+}
+catch (const std::ifstream::failure&amp;)
+{
+ cerr &lt;&lt; "people.xml: unable to open or read error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+
+ <!-- Chapater 6 -->
+
+
+ <h1><a name="6">6 Serialization</a></h1>
+
+ <p>We have already seen how to serialize an object model back to XML
+ in this guide before. In this chapter we will discuss the
+ serialization topic in more detail.</p>
+
+ <p>By default, the C++/Tree mapping provides a total of 8 overloaded
+ serialization functions. They differ in the output methods used to write
+ XML as well as the error reporting mechanisms. It is also possible to
+ generate types for root elements instead of parsing and serialization
+ functions. This may be useful if your XML vocabulary has multiple
+ root elements. For more information on element types refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#2.9">Section
+ 2.9, "Mapping for Global Elements"</a> in the C++/Tree Mapping User
+ Manual.</p>
+
+
+ <p>In this section we will discuss the most commonly
+ used version of serialization functions. For a comprehensive description
+ of serialization refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#4">Chapter
+ 4, "Serialization"</a> in the C++/Tree Mapping User Manual. For the
+ <code>people</code> global element from our person record vocabulary,
+ we will concentrate on the following serialization function:</p>
+
+ <pre class="c++">
+void
+people (std::ostream&amp; os,
+ const people_t&amp; x,
+ const xml_schema::namespace_infomap&amp; map =
+ xml_schema::namespace_infomap (),
+ const std::string&amp; encoding = "UTF-8",
+ xml_schema::flags f = 0);
+ </pre>
+
+ <p>This function serializes the object model passed as the second
+ argument to the standard output stream passed as the first
+ argument. The third argument is a namespace information map
+ which we will discuss in more detail in the next section.
+ The fourth argument is a character encoding that the resulting
+ XML document should be in. Possible valid values for this
+ argument are "US-ASCII", "ISO8859-1", "UTF-8", "UTF-16BE",
+ "UTF-16LE", "UCS-4BE", and "UCS-4LE". Finally, the flags
+ argument allows fine-tuning of the serialization process.
+ The following example shows how we can use the above serialization
+ function:</p>
+
+ <pre class="c++">
+people_t&amp; p = ...
+
+xml_schema::namespace_infomap map;
+map[""].schema = "people.xsd";
+
+// Serialize to stdout.
+//
+people (std::cout, p, map);
+
+// Serialize to a file.
+//
+std::ofstream ofs ("people.xml");
+people (ofs, p, map);
+
+// Serialize to a string.
+//
+std::ostringstream oss;
+people (oss, p, map);
+std::string xml (oss.str ());
+ </pre>
+
+
+ <h2><a name="6.1">6.1 Namespace and Schema Information</a></h2>
+
+ <p>While XML serialization can be done just from the object
+ model alone, it is often desirable to assign meaningful
+ prefixes to XML namespaces used in the vocabulary as
+ well as to provide the schema location information.
+ This is accomplished by passing the namespace information
+ map to the serialization function. The key in this map is
+ a namespace prefix that should be assigned to an XML namespace
+ specified in the <code>name</code> variable of the
+ map value. You can also assign an optional schema location for
+ this namespace in the <code>schema</code> variable. Based
+ on each key-value entry in this map, the serialization
+ function adds two attributes to the resulting XML document:
+ the namespace-prefix mapping attribute and schema location
+ attribute. The empty prefix indicates that the namespace
+ should be mapped without a prefix. For example, the following
+ map:</p>
+
+ <pre class="c++">
+xml_schema::namespace_infomap map;
+
+map[""].name = "http://www.example.com/example";
+map[""].schema = "example.xsd";
+
+map["x"].name = "http://www.w3.org/XML/1998/namespace";
+map["x"].schema = "xml.xsd";
+ </pre>
+
+ <p>Results in the following XML document:</p>
+
+ <pre class="xml">
+&lt;?xml version="1.0" ?>
+&lt;example
+ xmlns="http://www.example.com/example"
+ xmlns:x="http://www.w3.org/XML/1998/namespace"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.example.com/example example.xsd
+ http://www.w3.org/XML/1998/namespace xml.xsd">
+ </pre>
+
+ <p>The empty namespace indicates that the vocabulary has no target
+ namespace. For example, the following map results in only the
+ <code>noNamespaceSchemaLocation</code> attribute being added:</p>
+
+ <pre class="c++">
+xml_schema::namespace_infomap map;
+
+map[""].name = "";
+map[""].schema = "example.xsd";
+ </pre>
+
+ <h2><a name="6.2">6.2 Error Handling</a></h2>
+
+ <p>Similar to the parsing functions, the serialization functions offer a
+ number of ways to handle error conditions with the C++ exceptions being
+ the most commonly used mechanisms. As with parsing, the easiest way to
+ uniformly handle all possible serialization exceptions and print
+ detailed information about the error is to catch and print
+ <code>xml_schema::exception</code>:</p>
+
+ <pre class="c++">
+try
+{
+ people_t&amp; p = ...
+
+ xml_schema::namespace_infomap map;
+ map[""].schema = "people.xsd";
+
+ people (std::cout, p, map));
+}
+catch (const xml_schema::exception&amp; e)
+{
+ cerr &lt;&lt; e &lt;&lt; endl;
+}
+ </pre>
+
+ <p>The most commonly encountered serialization exception is
+ <code>xml_schema::serialization</code>. It is thrown
+ when the XML serialization in the underlying XML writer
+ fails. It encapsulates various diagnostics information
+ such as the file name, line and column numbers, as well as the
+ error or warning message for each entry. For more information
+ about this and other exceptions that can be thrown during
+ serialization, refer to
+ <a href="https://www.codesynthesis.com/projects/xsd/documentation/cxx/tree/manual/#4.4">Section
+ 4.4, "Error Handling"</a> in the C++/Tree Mapping
+ User Manual.</p>
+
+ <p>Note that if you are serializing to <code>std::ostream</code> on
+ which exceptions are not enabled, then you will need to check the
+ stream state after the call to the serialization function in order
+ to detect any possible stream failures, for example:</p>
+
+ <pre class="c++">
+std::ofstream ofs ("people.xml");
+
+if (ofs.fail ())
+{
+ cerr &lt;&lt; "people.xml: unable to open" &lt;&lt; endl;
+ return 1;
+}
+
+people (ofs, p, map));
+
+if (ofs.fail ())
+{
+ cerr &lt;&lt; "people.xml: write error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ <p>The above example can be rewritten to use exceptions as
+ shown below:</p>
+
+ <pre class="c++">
+try
+{
+ std::ofstream ofs;
+ ofs.exceptions (std::ofstream::badbit | std::ofstream::failbit);
+ ofs.open ("people.xml");
+
+ people (ofs, p, map));
+}
+catch (const std::ofstream::failure&amp;)
+{
+ cerr &lt;&lt; "people.xml: unable to open or write error" &lt;&lt; endl;
+ return 1;
+}
+ </pre>
+
+ </div>
+</div>
+
+</body>
+</html>
diff --git a/doc/cxx/tree/manual/index.xhtml b/doc/cxx/tree/manual/index.xhtml
new file mode 100644
index 0000000..f455bff
--- /dev/null
+++ b/doc/cxx/tree/manual/index.xhtml
@@ -0,0 +1,6826 @@
+<?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; 2005-2023 Code Synthesis"/>
+ <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; 2005-2023 Code Synthesis.</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</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++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</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::unique_ptr</code>
+ or <code>std::auto_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::unique_ptr</code>
+ or <code>std::auto_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::unique_ptr</code> (C++11) or <code>std::auto_ptr</code>
+ (C++98), 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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::unique_ptr</code> or
+ <code>std::auto_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::[unique|auto]_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::[unique|auto]_ptr&lt;member_type>
+ detach_member ();
+ ...
+
+};
+ </pre>
+
+ <p>This function detaches the value from the tree leaving the member
+ value uninitialized. Accessing such an uninitialized value prior to
+ re-initializing it results in undefined behavior.</p>
+
+ <p>The following code shows how one could use this mapping:</p>
+
+ <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++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
+
+ // 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
+}
+ </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::unique_ptr</code> or
+ <code>std::auto_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::[unique|auto]_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>[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;X>);
+
+ // Detach and return the contained value.
+ //
+ std::[unique|auto]_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++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
+
+ // 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
+}
+ </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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_ptr&lt;X>)
+
+ iterator
+ insert (iterator position, std::[unique|auto]_ptr&lt;X>)
+
+ std::[unique|auto]_ptr&lt;X>
+ detach_back (bool pop = true);
+
+ iterator
+ detach (iterator position,
+ std::[unique|auto]_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++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
+
+ // 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
+
+ // 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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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:</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>
+using 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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_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::[unique|auto]_ptr&lt;value_type>);
+
+ // Constructors.
+ //
+ root (const value_type&amp;);
+
+ root (std::[unique|auto]_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::[unique|auto]_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::unique_ptr</code>
+ or <code>std::auto_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.
+
+unique_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::unique_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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (std::istream&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (std::istream&amp;,
+ xercesc::DOMErrorHandler&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+
+std::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (xercesc::InputSource&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (const xercesc::DOMDocument&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;type>
+name (xml_schema::dom::[unique|auto]_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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_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::unique_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::unique_ptr;
+
+unique_ptr&lt;type> r1 (name ("test.xml"));
+unique_ptr&lt;type> r2 (name ("https://www.codesynthesis.com/test.xml"));
+ </pre>
+
+ <p>Or, in the C++98 mode:</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>
+
+ <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::unique_ptr;
+
+{
+ std::ifstream ifs ("test.xml");
+ unique_ptr&lt;type> r (name (ifs, "test.xml"));
+}
+
+{
+ std::string str ("..."); // Some XML fragment.
+ std::istringstream iss (str);
+ unique_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::unique_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++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.
+
+// 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.
+ </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::[unique|auto]_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::unique_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::unique_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::unique_ptr;
+
+// Obtain the object model.
+//
+unique_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.
+ //
+ unique_ptr&lt;XMLFormatTarget> ft;
+
+ if (argc != 2)
+ {
+ ft = unique_ptr&lt;XMLFormatTarget> (new StdOutFormatTarget ());
+ }
+ else
+ {
+ ft = unique_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::unique_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::unique_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::unique_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::unique_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::unique_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>
diff --git a/doc/cxx/tree/manual/index.xhtml.in b/doc/cxx/tree/manual/index.xhtml.in
new file mode 100644
index 0000000..5a7240a
--- /dev/null
+++ b/doc/cxx/tree/manual/index.xhtml.in
@@ -0,0 +1,6826 @@
+<?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; @copyright@"/>
+ <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; @copyright@.</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ contains a collection of examples and a README file with an overview
+ of each example.</li>
+
+ <li>The <code>README</code> file in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a> package
+ explains how to build the examples.</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++ 2011 (C++11)
+ and ISO/IEC C++ 1998/2003 (C++98). 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 guide use
+ C++11, the document explains the C++11/98 usage difference and so
+ they can easily be converted to C++98.</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::unique_ptr</code>
+ or <code>std::auto_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::unique_ptr</code>
+ or <code>std::auto_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::unique_ptr</code> (C++11) or <code>std::auto_ptr</code>
+ (C++98), 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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::unique_ptr</code> or
+ <code>std::auto_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::[unique|auto]_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::[unique|auto]_ptr&lt;member_type>
+ detach_member ();
+ ...
+
+};
+ </pre>
+
+ <p>This function detaches the value from the tree leaving the member
+ value uninitialized. Accessing such an uninitialized value prior to
+ re-initializing it results in undefined behavior.</p>
+
+ <p>The following code shows how one could use this mapping:</p>
+
+ <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++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
+
+ // 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
+}
+ </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::unique_ptr</code> or
+ <code>std::auto_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::[unique|auto]_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>[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;X>);
+
+ // Detach and return the contained value.
+ //
+ std::[unique|auto]_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++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
+
+ // 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
+}
+ </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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_ptr&lt;X>)
+
+ iterator
+ insert (iterator position, std::[unique|auto]_ptr&lt;X>)
+
+ std::[unique|auto]_ptr&lt;X>
+ detach_back (bool pop = true);
+
+ iterator
+ detach (iterator position,
+ std::[unique|auto]_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++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
+
+ // 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
+
+ // 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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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:</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>
+using 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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_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::[unique|auto]_ptr&lt;value_type>);
+
+ // Constructors.
+ //
+ root (const value_type&amp;);
+
+ root (std::[unique|auto]_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::[unique|auto]_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::unique_ptr</code>
+ or <code>std::auto_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.
+
+unique_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::unique_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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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>cxx/tree/</code> directory in the
+ <a href="https://cppget.org/xsd-examples">xsd-examples</a>
+ package.</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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (std::istream&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (std::istream&amp;,
+ xercesc::DOMErrorHandler&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+
+std::[unique|auto]_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::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (xercesc::InputSource&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_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::[unique|auto]_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::[unique|auto]_ptr&lt;type>
+name (const xercesc::DOMDocument&amp;,
+ xml_schema::flags = 0,
+ const xml_schema::properties&amp; = xml_schema::properties ());
+
+std::[unique|auto]_ptr&lt;type>
+name (xml_schema::dom::[unique|auto]_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::unique_ptr</code> or <code>std::auto_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::[unique|auto]_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::unique_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::unique_ptr;
+
+unique_ptr&lt;type> r1 (name ("test.xml"));
+unique_ptr&lt;type> r2 (name ("https://www.codesynthesis.com/test.xml"));
+ </pre>
+
+ <p>Or, in the C++98 mode:</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>
+
+ <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::unique_ptr;
+
+{
+ std::ifstream ifs ("test.xml");
+ unique_ptr&lt;type> r (name (ifs, "test.xml"));
+}
+
+{
+ std::string str ("..."); // Some XML fragment.
+ std::istringstream iss (str);
+ unique_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::unique_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++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.
+
+// 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.
+ </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::[unique|auto]_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::unique_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::unique_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::unique_ptr;
+
+// Obtain the object model.
+//
+unique_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.
+ //
+ unique_ptr&lt;XMLFormatTarget> ft;
+
+ if (argc != 2)
+ {
+ ft = unique_ptr&lt;XMLFormatTarget> (new StdOutFormatTarget ());
+ }
+ else
+ {
+ ft = unique_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::unique_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::unique_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::unique_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::unique_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::unique_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>
diff --git a/doc/cxx/tree/manual/manual.html2ps.in b/doc/cxx/tree/manual/manual.html2ps.in
new file mode 100644
index 0000000..5629122
--- /dev/null
+++ b/doc/cxx/tree/manual/manual.html2ps.in
@@ -0,0 +1,66 @@
+@@html2ps {
+ option {
+ toc: hb;
+ colour: 1;
+ hyphenate: 1;
+ titlepage: 1;
+ }
+
+ datefmt: "%B %Y";
+
+ titlepage {
+ content: "
+<div align=center>
+ <h1><big>C++/Tree Mapping User Manual</big></h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+ <h1>&nbsp;</h1>
+</div>
+ <p>Revision $[revision] &nbsp;&nbsp;&nbsp; $D</p>
+ <p>Copyright &#169; @copyright@.</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>";
+ }
+
+ toc {
+ indent: 2em;
+ }
+
+ header {
+ odd-right: $H;
+ even-left: $H;
+ }
+
+ footer {
+ odd-left: $D;
+ odd-center: $T, v$[revision];
+ odd-right: $N;
+
+ even-left: $N;
+ even-center: $T, v$[revision];
+ even-right: $D;
+ }
+}
+
+body {
+ font-size: 12pt;
+ text-align: justify;
+}
+
+pre {
+ font-size: 10pt;
+}
generated by cgit v1.2.3 (git 2.25.1) at 2025-11-04 12:23:18 +0000