Skip to content

Commit

Permalink
docs: Update documentation to address PUGIXML_HAS_STRING_VIEW changes
Browse files Browse the repository at this point in the history
The PUGIXML_STRING_VIEW define is no longer necessary but
_HAS_STRING_VIEW can be enabled manually if the compiler supports it
without advertising C++17 support.
  • Loading branch information
zeux committed Oct 30, 2024
1 parent ca4f7cf commit d5f14ad
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 8 deletions.
2 changes: 1 addition & 1 deletion docs/manual.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ NOTE: In that example `PUGIXML_API` is inconsistent between several source files

[[PUGIXML_HAS_LONG_LONG]]`PUGIXML_HAS_LONG_LONG` define enables support for `long long` type in pugixml. This define is automatically enabled if your platform is known to have `long long` support (i.e. has C{plus}{plus}11 support or uses a reasonably modern version of a known compiler); if pugixml does not recognize that your platform supports `long long` but in fact it does, you can enable the define manually.

[[PUGIXML_HAS_STRING_VIEW]]`PUGIXML_HAS_STRING_VIEW` define enables function overloads that accept `std::basic_string_view` arguments. This define is automatically enabled if built targeting C++17 or later AND if `PUGIXML_STRING_VIEW` is also defined. The requirement to additionally define `PUGIXML_STRING_VIEW` will be retired in a future version.
[[PUGIXML_HAS_STRING_VIEW]]`PUGIXML_HAS_STRING_VIEW` define enables function overloads that accept `std::string_view` arguments. This define is automatically enabled if built targeting C{plus}{plus}17 or later; if pugixml does not recognize that your platform supports `std::string_view` but in fact it does, you can enable the define manually.

[[install.portability]]
=== Portability
Expand Down
13 changes: 6 additions & 7 deletions docs/manual.html
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.23">
<meta name="generator" content="Asciidoctor 2.0.20">
<meta name="author" content="website, repository">
<title>pugixml 1.14 manual</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
Expand Down Expand Up @@ -141,7 +141,7 @@
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
Expand All @@ -163,7 +163,6 @@
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
Expand Down Expand Up @@ -329,7 +328,7 @@
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
Expand Down Expand Up @@ -1028,7 +1027,7 @@ <h4 id="install.building.config"><a class="anchor" href="#install.building.confi
<p><a id="PUGIXML_HAS_LONG_LONG"></a><code>PUGIXML_HAS_LONG_LONG</code> define enables support for <code>long long</code> type in pugixml. This define is automatically enabled if your platform is known to have <code>long long</code> support (i.e. has C&#43;&#43;11 support or uses a reasonably modern version of a known compiler); if pugixml does not recognize that your platform supports <code>long long</code> but in fact it does, you can enable the define manually.</p>
</div>
<div class="paragraph">
<p><a id="PUGIXML_HAS_STRING_VIEW"></a><code>PUGIXML_HAS_STRING_VIEW</code> define enables function overloads that accept <code>std::basic_string_view</code> arguments. This define is automatically enabled if built targeting c++17 or later AND if <code>PUGIXML_STRING_VIEW</code> is also defined. The requirement to additionally define <code>PUGIXML_STRING_VIEW</code> will be retired in a future version.</p>
<p><a id="PUGIXML_HAS_STRING_VIEW"></a><code>PUGIXML_HAS_STRING_VIEW</code> define enables function overloads that accept <code>std::string_view</code> arguments. This define is automatically enabled if built targeting C&#43;&#43;17 or later; if pugixml does not recognize that your platform supports <code>std::string_view</code> but in fact it does, you can enable the define manually.</p>
</div>
</div>
</div>
Expand Down Expand Up @@ -1295,7 +1294,7 @@ <h3 id="dom.unicode"><a class="anchor" href="#dom.unicode"></a><a class="link" h
</div>
<div class="paragraph">
<p><a id="char_t"></a><a id="string_t"></a><a id="string_view_t"></a>
There is a special type, <code>pugi::char_t</code>, that is defined as the character type and depends on the library configuration; it will be also used in the documentation hereafter. There is also a type <code>pugi::string_t</code>, which is defined as the STL string of the character type; it corresponds to <code>std::string</code> in char mode and to <code>std::wstring</code> in wchar_t mode. Similarly, <code>string_view_t</code> is defined to be <code>std::basic_string_view&lt;char_t&gt;</code>. Overloads for <code>string_view_t</code> are only available when building for c++17 or later (see <code>PUGIXML_HAS_STRING_VIEW</code>).</p>
There is a special type, <code>pugi::char_t</code>, that is defined as the character type and depends on the library configuration; it will be also used in the documentation hereafter. There is also a type <code>pugi::string_t</code>, which is defined as the STL string of the character type; it corresponds to <code>std::string</code> in char mode and to <code>std::wstring</code> in wchar_t mode. Similarly, <code>string_view_t</code> is defined to be <code>std::basic_string_view&lt;char_t&gt;</code>. Overloads for <code>string_view_t</code> are only available when building for C++17 or later (see <code>PUGIXML_HAS_STRING_VIEW</code>).</p>
</div>
<div class="paragraph">
<p>In addition to the interface, the internal implementation changes to store XML data as <code>pugi::char_t</code>; this means that these two modes have different memory usage characteristics - generally UTF-8 mode is more memory and performance efficient, especially if <code>sizeof(wchar_t)</code> is 4. The conversion to <code>pugi::char_t</code> upon document loading and from <code>pugi::char_t</code> upon document saving happen automatically, which also carries minor performance penalty. The general advice however is to select the character mode based on usage scenario, i.e. if UTF-8 is inconvenient to process and most of your XML data is non-ASCII, wchar_t mode is probably a better choice.</p>
Expand Down Expand Up @@ -6217,7 +6216,7 @@ <h3 id="apiref.functions"><a class="anchor" href="#apiref.functions"></a><a clas
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-10-27 09:31:16 -0700
Last updated 2024-10-30 10:34:38 -0700
</div>
</div>
</body>
Expand Down

0 comments on commit d5f14ad

Please sign in to comment.