-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathUsingLibcxx.html
390 lines (379 loc) · 29.9 KB
/
UsingLibcxx.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using libc++ — libc++ 11.0 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Building libc++" href="BuildingLibcxx.html" />
<link rel="prev" title="Libc++ 11.0.0 (In-Progress) Release Notes" href="ReleaseNotes.html" />
</head><body>
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>libc++ 11.0 documentation</span></a></h1>
<h2 class="heading"><span>Using libc++</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="ReleaseNotes.html">Libc++ 11.0.0 (In-Progress) Release Notes</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="BuildingLibcxx.html">Building libc++</a>  »
</p>
</div>
<div class="content">
<div class="section" id="using-libc">
<h1>Using libc++<a class="headerlink" href="#using-libc" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#getting-started" id="id1">Getting Started</a></li>
<li><a class="reference internal" href="#using-filesystem" id="id2">Using <code class="docutils literal notranslate"><span class="pre"><filesystem></span></code></a></li>
<li><a class="reference internal" href="#using-libc-experimental-and-experimental" id="id3">Using libc++experimental and <code class="docutils literal notranslate"><span class="pre"><experimental/...></span></code></a></li>
<li><a class="reference internal" href="#using-libc-on-linux" id="id4">Using libc++ on Linux</a><ul>
<li><a class="reference internal" href="#using-libc-with-gcc" id="id5">Using libc++ with GCC</a></li>
<li><a class="reference internal" href="#gdb-pretty-printers-for-libc" id="id6">GDB Pretty printers for libc++</a></li>
</ul>
</li>
<li><a class="reference internal" href="#libc-configuration-macros" id="id7">Libc++ Configuration Macros</a><ul>
<li><a class="reference internal" href="#c-17-specific-configuration-macros" id="id8">C++17 Specific Configuration Macros</a></li>
<li><a class="reference internal" href="#c-2a-specific-configuration-macros" id="id9">C++2a Specific Configuration Macros:</a></li>
</ul>
</li>
<li><a class="reference internal" href="#libc-extensions" id="id10">Libc++ Extensions</a><ul>
<li><a class="reference internal" href="#extended-applications-of-nodiscard" id="id11">Extended applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code></a><ul>
<li><a class="reference internal" href="#entities-declared-with-libcpp-nodiscard-ext" id="id12">Entities declared with <code class="docutils literal notranslate"><span class="pre">_LIBCPP_NODISCARD_EXT</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="getting-started">
<h2><a class="toc-backref" href="#id1">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>If you already have libc++ installed you can use it with clang.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ test.cpp
$ clang++ -std<span class="o">=</span>c++11 -stdlib<span class="o">=</span>libc++ test.cpp
</pre></div>
</div>
<p>On macOS and FreeBSD libc++ is the default standard library
and the <code class="docutils literal notranslate"><span class="pre">-stdlib=libc++</span></code> is not required.</p>
<p id="alternate-libcxx">If you want to select an alternate installation of libc++ you
can use the following options.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -std<span class="o">=</span>c++11 -stdlib<span class="o">=</span>libc++ -nostdinc++ <span class="se">\</span>
-I<libcxx-install-prefix>/include/c++/v1 <span class="se">\</span>
-L<libcxx-install-prefix>/lib <span class="se">\</span>
-Wl,-rpath,<libcxx-install-prefix>/lib <span class="se">\</span>
test.cpp
</pre></div>
</div>
<p>The option <code class="docutils literal notranslate"><span class="pre">-Wl,-rpath,<libcxx-install-prefix>/lib</span></code> adds a runtime library
search path. Meaning that the systems dynamic linker will look for libc++ in
<code class="docutils literal notranslate"><span class="pre"><libcxx-install-prefix>/lib</span></code> whenever the program is run. Alternatively the
environment variable <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> (<code class="docutils literal notranslate"><span class="pre">DYLD_LIBRARY_PATH</span></code> on macOS) can
be used to change the dynamic linkers search paths after a program is compiled.</p>
<p>An example of using <code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ -nostdinc++ <span class="se">\</span>
-I<libcxx-install-prefix>/include/c++/v1
-L<libcxx-install-prefix>/lib <span class="se">\</span>
test.cpp -o
$ ./a.out <span class="c1"># Searches for libc++ in the systems library paths.</span>
$ <span class="nb">export</span> <span class="nv">LD_LIBRARY_PATH</span><span class="o">=</span><libcxx-install-prefix>/lib
$ ./a.out <span class="c1"># Searches for libc++ along LD_LIBRARY_PATH</span>
</pre></div>
</div>
</div>
<div class="section" id="using-filesystem">
<h2><a class="toc-backref" href="#id2">Using <code class="docutils literal notranslate"><span class="pre"><filesystem></span></code></a><a class="headerlink" href="#using-filesystem" title="Permalink to this headline">¶</a></h2>
<p>Prior to LLVM 9.0, libc++ provides the implementation of the filesystem library
in a separate static library. Users of <code class="docutils literal notranslate"><span class="pre"><filesystem></span></code> and <code class="docutils literal notranslate"><span class="pre"><experimental/filesystem></span></code>
are required to link <code class="docutils literal notranslate"><span class="pre">-lc++fs</span></code>. Prior to libc++ 7.0, users of
<code class="docutils literal notranslate"><span class="pre"><experimental/filesystem></span></code> were required to link libc++experimental.</p>
<p>Starting with LLVM 9.0, support for <code class="docutils literal notranslate"><span class="pre"><filesystem></span></code> is provided in the main
library and nothing special is required to use <code class="docutils literal notranslate"><span class="pre"><filesystem></span></code>.</p>
</div>
<div class="section" id="using-libc-experimental-and-experimental">
<h2><a class="toc-backref" href="#id3">Using libc++experimental and <code class="docutils literal notranslate"><span class="pre"><experimental/...></span></code></a><a class="headerlink" href="#using-libc-experimental-and-experimental" title="Permalink to this headline">¶</a></h2>
<p>Libc++ provides implementations of experimental technical specifications
in a separate library, <code class="docutils literal notranslate"><span class="pre">libc++experimental.a</span></code>. Users of <code class="docutils literal notranslate"><span class="pre"><experimental/...></span></code>
headers may be required to link <code class="docutils literal notranslate"><span class="pre">-lc++experimental</span></code>.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -std<span class="o">=</span>c++14 -stdlib<span class="o">=</span>libc++ test.cpp -lc++experimental
</pre></div>
</div>
<p>Libc++experimental.a may not always be available, even when libc++ is already
installed. For information on building libc++experimental from source see
<a class="reference internal" href="BuildingLibcxx.html#build-instructions"><span class="std std-ref">Building Libc++</span></a> and
<a class="reference internal" href="BuildingLibcxx.html#libc-experimental-options"><span class="std std-ref">libc++experimental CMake Options</span></a>.</p>
<p>Also see the <a class="reference external" href="http://libcxx.llvm.org/ts1z_status.html">Experimental Library Implementation Status</a>
page.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<dl class="last docutils">
<dt>Experimental libraries are Experimental.</dt>
<dd><ul class="first last simple">
<li>The contents of the <code class="docutils literal notranslate"><span class="pre"><experimental/...></span></code> headers and <code class="docutils literal notranslate"><span class="pre">libc++experimental.a</span></code>
library will not remain compatible between versions.</li>
<li>No guarantees of API or ABI stability are provided.</li>
<li>When we implement the standardized version of an experimental feature,
the experimental feature is removed two releases after the non-experimental
version has shipped. The full policy is explained <a class="reference internal" href="DesignDocs/ExperimentalFeatures.html#id1"><span class="std std-ref">here</span></a>.</li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section" id="using-libc-on-linux">
<h2><a class="toc-backref" href="#id4">Using libc++ on Linux</a><a class="headerlink" href="#using-libc-on-linux" title="Permalink to this headline">¶</a></h2>
<p>On Linux libc++ can typically be used with only ‘-stdlib=libc++’. However
some libc++ installations require the user manually link libc++abi themselves.
If you are running into linker errors when using libc++ try adding ‘-lc++abi’
to the link line. For example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
</pre></div>
</div>
<p>Alternately, you could just add libc++abi to your libraries list, which in
most situations will give the same result:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ test.cpp -lc++abi
</pre></div>
</div>
<div class="section" id="using-libc-with-gcc">
<h3><a class="toc-backref" href="#id5">Using libc++ with GCC</a><a class="headerlink" href="#using-libc-with-gcc" title="Permalink to this headline">¶</a></h3>
<p>GCC does not provide a way to switch from libstdc++ to libc++. You must manually
configure the compile and link commands.</p>
<p>In particular you must tell GCC to remove the libstdc++ include directories
using <code class="docutils literal notranslate"><span class="pre">-nostdinc++</span></code> and to not link libstdc++.so using <code class="docutils literal notranslate"><span class="pre">-nodefaultlibs</span></code>.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">-nodefaultlibs</span></code> removes all of the standard system libraries and
not just libstdc++ so they must be manually linked. For example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 <span class="se">\</span>
test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
</pre></div>
</div>
</div>
<div class="section" id="gdb-pretty-printers-for-libc">
<h3><a class="toc-backref" href="#id6">GDB Pretty printers for libc++</a><a class="headerlink" href="#gdb-pretty-printers-for-libc" title="Permalink to this headline">¶</a></h3>
<p>GDB does not support pretty-printing of libc++ symbols by default. Unfortunately
libc++ does not provide pretty-printers itself. However there are 3rd
party implementations available and although they are not officially
supported by libc++ they may be useful to users.</p>
<p>Known 3rd Party Implementations Include:</p>
<ul class="simple">
<li><a class="reference external" href="https://github.com/koutheir/libcxx-pretty-printers">Koutheir’s libc++ pretty-printers</a>.</li>
</ul>
</div>
</div>
<div class="section" id="libc-configuration-macros">
<h2><a class="toc-backref" href="#id7">Libc++ Configuration Macros</a><a class="headerlink" href="#libc-configuration-macros" title="Permalink to this headline">¶</a></h2>
<p>Libc++ provides a number of configuration macros which can be used to enable
or disable extended libc++ behavior, including enabling “debug mode” or
thread safety annotations.</p>
<dl class="docutils">
<dt><strong>_LIBCPP_DEBUG</strong>:</dt>
<dd>See <a class="reference internal" href="DesignDocs/DebugMode.html#using-debug-mode"><span class="std std-ref">Using Debug Mode</span></a> for more information.</dd>
<dt><strong>_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS</strong>:</dt>
<dd>This macro is used to enable -Wthread-safety annotations on libc++’s
<code class="docutils literal notranslate"><span class="pre">std::mutex</span></code> and <code class="docutils literal notranslate"><span class="pre">std::lock_guard</span></code>. By default these annotations are
disabled and must be manually enabled by the user.</dd>
<dt><strong>_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS</strong>:</dt>
<dd>This macro is used to disable all visibility annotations inside libc++.
Defining this macro and then building libc++ with hidden visibility gives a
build of libc++ which does not export any symbols, which can be useful when
building statically for inclusion into another library.</dd>
<dt><strong>_LIBCPP_DISABLE_EXTERN_TEMPLATE</strong>:</dt>
<dd>This macro is used to disable extern template declarations in the libc++
headers. The intended use case is for clients who wish to use the libc++
headers without taking a dependency on the libc++ library itself.</dd>
<dt><strong>_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION</strong>:</dt>
<dd><p class="first">This macro is used to re-enable an extension in <cite>std::tuple</cite> which allowed
it to be implicitly constructed from fewer initializers than contained
elements. Elements without an initializer are default constructed. For example:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">tuple</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="o">></span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">{</span><span class="s">"hello world"</span><span class="p">,</span> <span class="mi">42</span><span class="p">};</span> <span class="c1">// default constructs error_code</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Since libc++ 4.0 this extension has been disabled by default. This macro
may be defined to re-enable it in order to support existing code that depends
on the extension. New use of this extension should be discouraged.
See <a class="reference external" href="http://llvm.org/PR27374">PR 27374</a> for more information.</p>
<p>Note: The “reduced-arity-initialization” extension is still offered but only
for explicit conversions. Example:</p>
<div class="last highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">auto</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
<span class="k">using</span> <span class="n">Tup</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">tuple</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="o">></span><span class="p">;</span>
<span class="k">return</span> <span class="n">Tup</span><span class="p">{</span><span class="s">"hello world"</span><span class="p">,</span> <span class="mi">42</span><span class="p">};</span> <span class="c1">// explicit constructor called. OK.</span>
<span class="p">}</span>
</pre></div>
</div>
</dd>
<dt><strong>_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS</strong>:</dt>
<dd><p class="first">This macro disables the additional diagnostics generated by libc++ using the
<cite>diagnose_if</cite> attribute. These additional diagnostics include checks for:</p>
<blockquote class="last">
<div><ul class="simple">
<li>Giving <cite>set</cite>, <cite>map</cite>, <cite>multiset</cite>, <cite>multimap</cite> and their <cite>unordered_</cite>
counterparts a comparator which is not const callable.</li>
<li>Giving an unordered associative container a hasher that is not const
callable.</li>
</ul>
</div></blockquote>
</dd>
<dt><strong>_LIBCPP_NO_VCRUNTIME</strong>:</dt>
<dd><p class="first">Microsoft’s C and C++ headers are fairly entangled, and some of their C++
headers are fairly hard to avoid. In particular, <cite>vcruntime_new.h</cite> gets pulled
in from a lot of other headers and provides definitions which clash with
libc++ headers, such as <cite>nothrow_t</cite> (note that <cite>nothrow_t</cite> is a struct, so
there’s no way for libc++ to provide a compatible definition, since you can’t
have multiple definitions).</p>
<p class="last">By default, libc++ solves this problem by deferring to Microsoft’s vcruntime
headers where needed. However, it may be undesirable to depend on vcruntime
headers, since they may not always be available in cross-compilation setups,
or they may clash with other headers. The <cite>_LIBCPP_NO_VCRUNTIME</cite> macro
prevents libc++ from depending on vcruntime headers. Consequently, it also
prevents libc++ headers from being interoperable with vcruntime headers (from
the aforementioned clashes), so users of this macro are promising to not
attempt to combine libc++ headers with the problematic vcruntime headers. This
macro also currently prevents certain <cite>operator new</cite>/<cite>operator delete</cite>
replacement scenarios from working, e.g. replacing <cite>operator new</cite> and
expecting a non-replaced <cite>operator new[]</cite> to call the replaced <cite>operator new</cite>.</p>
</dd>
<dt><strong>_LIBCPP_ENABLE_NODISCARD</strong>:</dt>
<dd>Allow the library to add <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> attributes to entities not specified
as <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> by the current language dialect. This includes
backporting applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> from newer dialects and
additional extended applications at the discretion of the library. All
additional applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> are disabled by default.
See <a class="reference internal" href="#nodiscard-extension"><span class="std std-ref">Extended Applications of [[nodiscard]]</span></a> for
more information.</dd>
<dt><strong>_LIBCPP_DISABLE_NODISCARD_EXT</strong>:</dt>
<dd>This macro prevents the library from applying <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> to entities
purely as an extension. See <a class="reference internal" href="#nodiscard-extension"><span class="std std-ref">Extended Applications of [[nodiscard]]</span></a>
for more information.</dd>
<dt><strong>_LIBCPP_DISABLE_DEPRECATION_WARNINGS</strong>:</dt>
<dd>This macro disables warnings when using deprecated components. For example,
using <cite>std::auto_ptr</cite> when compiling in C++11 mode will normally trigger a
warning saying that <cite>std::auto_ptr</cite> is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.</dd>
</dl>
<div class="section" id="c-17-specific-configuration-macros">
<h3><a class="toc-backref" href="#id8">C++17 Specific Configuration Macros</a><a class="headerlink" href="#c-17-specific-configuration-macros" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES</strong>:</dt>
<dd>This macro is used to re-enable all the features removed in C++17. The effect
is equivalent to manually defining each macro listed below.</dd>
<dt><strong>_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS</strong>:</dt>
<dd>This macro is used to re-enable the <cite>set_unexpected</cite>, <cite>get_unexpected</cite>, and
<cite>unexpected</cite> functions, which were removed in C++17.</dd>
<dt><strong>_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR</strong>:</dt>
<dd>This macro is used to re-enable <cite>std::auto_ptr</cite> in C++17.</dd>
</dl>
</div>
<div class="section" id="c-2a-specific-configuration-macros">
<h3><a class="toc-backref" href="#id9">C++2a Specific Configuration Macros:</a><a class="headerlink" href="#c-2a-specific-configuration-macros" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17</strong>:</dt>
<dd>This macro can be used to disable diagnostics emitted from functions marked
<code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> in dialects after C++17. See <a class="reference internal" href="#nodiscard-extension"><span class="std std-ref">Extended Applications of [[nodiscard]]</span></a>
for more information.</dd>
</dl>
</div>
</div>
<div class="section" id="libc-extensions">
<h2><a class="toc-backref" href="#id10">Libc++ Extensions</a><a class="headerlink" href="#libc-extensions" title="Permalink to this headline">¶</a></h2>
<p>This section documents various extensions provided by libc++, how they’re
provided, and any information regarding how to use them.</p>
<div class="section" id="extended-applications-of-nodiscard">
<span id="nodiscard-extension"></span><h3><a class="toc-backref" href="#id11">Extended applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code></a><a class="headerlink" href="#extended-applications-of-nodiscard" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> attribute is intended to help users find bugs where
function return values are ignored when they shouldn’t be. After C++17 the
C++ standard has started to declared such library functions as <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code>.
However, this application is limited and applies only to dialects after C++17.
Users who want help diagnosing misuses of STL functions may desire a more
liberal application of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code>.</p>
<p>For this reason libc++ provides an extension that does just that! The
extension must be enabled by defining <code class="docutils literal notranslate"><span class="pre">_LIBCPP_ENABLE_NODISCARD</span></code>. The extended
applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> takes two forms:</p>
<ol class="arabic simple">
<li>Backporting <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> to entities declared as such by the
standard in newer dialects, but not in the present one.</li>
<li>Extended applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code>, at the libraries discretion,
applied to entities never declared as such by the standard.</li>
</ol>
<p>Users may also opt-out of additional applications <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> using
additional macros.</p>
<p>Applications of the first form, which backport <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> from a newer
dialect may be disabled using macros specific to the dialect it was added. For
example <code class="docutils literal notranslate"><span class="pre">_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17</span></code>.</p>
<p>Applications of the second form, which are pure extensions, may be disabled
by defining <code class="docutils literal notranslate"><span class="pre">_LIBCPP_DISABLE_NODISCARD_EXT</span></code>.</p>
<div class="section" id="entities-declared-with-libcpp-nodiscard-ext">
<h4><a class="toc-backref" href="#id12">Entities declared with <code class="docutils literal notranslate"><span class="pre">_LIBCPP_NODISCARD_EXT</span></code></a><a class="headerlink" href="#entities-declared-with-libcpp-nodiscard-ext" title="Permalink to this headline">¶</a></h4>
<p>This section lists all extended applications of <code class="docutils literal notranslate"><span class="pre">[[nodiscard]]</span></code> to entities
which no dialect declares as such (See the second form described above).</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">adjacent_find</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">all_of</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">any_of</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">binary_search</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">clamp</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">count_if</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">count</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">equal_range</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">equal</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">find_end</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">find_first_of</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">find_if_not</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">find_if</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">find</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">get_temporary_buffer</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">includes</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_heap_until</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_heap</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_partitioned</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_permutation</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_sorted_until</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">is_sorted</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">lexicographical_compare</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">lower_bound</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">max_element</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">max</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">min_element</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">min</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">minmax_element</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">minmax</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">mismatch</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">none_of</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">remove_if</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">remove</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">search_n</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">search</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">unique</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">upper_bound</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">lock_guard</span></code>’s constructors</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="ReleaseNotes.html">Libc++ 11.0.0 (In-Progress) Release Notes</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="BuildingLibcxx.html">Building libc++</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2018, LLVM Project.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>